Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Verwalten von Unternehmenskonten

Du kannst dein Unternehmenskonto und die zugehörigen Organisationen mit der GraphQL-API verwalten.

Informationen zum Verwalten von Unternehmenskonten mit GraphQL

Du kannst die Unternehmenskonten-API und die Überwachungsprotokoll-API verwenden, die nur als GraphQL-APIs verfügbar sind, um Änderungen in deiner Organisation zu überwachen und vorzunehmen sowie konform zu bleiben.

Die Endpunkte des Unternehmenskontos funktionieren sowohl für GitHub Enterprise Cloud als auch für GitHub Enterprise Server.

Mit GraphQL kannst du nur die von dir angegebenen Daten anfordern und zurückgeben. Beispielsweise kannst du eine GraphQL-Abfrage erstellen oder Informationen anfordern, um alle neuen Organisationsmitglieder anzuzeigen, die deiner Organisation hinzugefügt wurden. Alternativ kannst du eine Änderung vornehmen, um einen Administrator zu deinem Unternehmenskonto einzuladen.

Mit der Überwachungsprotokoll-API kannst du überwachen, ob jemand:

  • auf deine Organisations- oder Repositoryeinstellungen zugreift
  • Berechtigungen ändert.
  • Benutzer in einer Organisation, einem Repository oder einem Team hinzufügt oder daraus entfernt.
  • Benutzer zum Administrator heraufstuft.
  • Berechtigungen einer GitHub-App ändert.

Mit der Überwachungsprotokoll-API kannst du Kopien deiner Überwachungsprotokolldaten aufbewahren. Bei Abfragen, die mit der Überwachungsprotokoll-API durchgeführt werden, kann die GraphQL-Antwort Daten für 90 bis 120 Tage enthalten. Eine Liste der mit der Überwachungsprotokoll-API verfügbaren Felder findest du unter AuditEntry-Schnittstelle.

Mit der Unternehmenskonten-API kannst du Folgendes durchführen:

  • Alle Organisationen und Repositorys auflisten und überprüfen, die zu deinem Unternehmenskonto gehören
  • Die Einstellungen des Unternehmenskontos ändern
  • Richtlinien für die Einstellungen deines Unternehmenskontos und die zugehörigen Organisationen konfigurieren
  • Administrator*innen zu deinem Unternehmenskonto einladen
  • Neue Organisationen in deinem Unternehmenskonto erstellen

Eine Liste der mit der Unternehmenskonten-API verfügbaren Felder findest du unter GraphQL-Felder und -Typen für die Unternehmenskonten-API.

Erste Schritte mit GraphQL für Unternehmenskonten

Führe die folgenden Schritte durch, um mit der Arbeit mit GraphQL zu beginnen und deine Unternehmenskonten zu verwalten:

  • Authentifizierung mit einem personal access token
  • Auswählen eines GraphQL-Clients oder Verwenden des GraphQL-Explorers
  • Einrichten von Insomnia zur Verwendung der GraphQL-API

Einige Beispielabfragen findest du unter Eine Beispielabfrage, bei der die Unternehmenskonten-API verwendet wird.

1. Authentifizierung mit einem personal access token

Die GraphQL-API unterstützt nur die Authentifizierung mithilfe eines personal access token (classic). Weitere Informationen findest du unter Erstellen eines personal access token.

  1. Um dich mit GraphQL zu authentifizieren, musst du ein personal access token aus den Entwicklereinstellungen generieren. Weitere Informationen findest du unter Erstellen eines personal access token.

  2. Gewähre deinem personal access token Administratorberechtigungen und Vollzugriff für die Bereiche von GHES, auf die du zugreifen möchtest. Es wird empfohlen, die folgenden Bereiche für dein personal access token auszuwählen, um Vollzugriff auf private Repositorys, Organisationen, Teams, Benutzerdaten sowie Zugriff auf Abrechnungs- und Profildaten des Unternehmens zu erhalten:

    • repo
    • admin:org
    • user
    • admin:enterprise

    Die spezifischen Bereiche des Unternehmenskontos sind:

    • admin:enterprise: Bietet vollständige Kontrolle über Unternehmen (beinhaltet manage_runners:enterprise, manage_billing:enterprise und read:enterprise)
    • manage_billing:enterprise: Lesen und Schreiben von Abrechnungsdaten des Unternehmens
    • read:enterprise: Lesen von Profildaten des Unternehmens
  3. Kopiere dein personal access token, und bewahre es an einem sicheren Ort auf, bis du es deinem GraphQL-Client hinzufügst.

2. Wähle einen GraphQL-Client aus.

Es wird empfohlen, GraphiQL oder einen anderen eigenständigen GraphQL-Client zu verwenden, mit dem du die Basis-URL konfigurieren kannst.

Alternativ kannst du diese GraphQL-Clients verwenden:

In den nächsten Schritten wird Insomnia verwendet.

3. Richte Insomnia zur Verwendung der GraphQL-API für GitHub mit Unternehmenskonten ein.

  1. Füge dem GraphQL-Client die Basis-URL und die POST-Methode hinzu. Wenn du GraphQL zum Anfordern von Informationen (Abfragen), Ändern von Informationen (Änderungen) oder Übertragen von Daten mit der GitHub-API verwendest, ist die Standard-HTTP-Methode POST, und die Basis-URL folgt dieser Syntax:

    • Für deine Unternehmensinstanz: https://<HOST>/api/graphql
    • Für GitHub Enterprise Cloud: https://api.github.com/graphql
  2. Öffne zum Authentifizieren das Menü „Authentifizierungsoptionen“, und wähle Bearertoken aus. Füge als Nächstes dein zuvor kopiertes personal access token hinzu.

    Berechtigungsoptionen für personal access token

    Berechtigungsoptionen für personal access token

  3. Gib Kopfzeileninformationen an.

    • Füge Content-Type als Header und application/json als Wert hinzu. Standardheader Header mit Vorschauwert für die Überwachungsprotokoll-API

Nun kannst du Abfragen tätigen.

Eine Beispielabfrage, bei der die Unternehmenskonten-API verwendet wird

Diese GraphQL-Abfrage fragt die Gesamtanzahl der public-Repositorys in allen Organisationen deiner Appliance mithilfe der Unternehmenskonten-API ab. Ersetze <enterprise-account-name> durch den Handle deines Unternehmenskontos, um diese Abfrage anzupassen. Wenn sich dein Unternehmenskonto beispielsweise unter https://github.com/enterprises/octo-enterprise befindet, ersetze <enterprise-account-name> durch octo-enterprise.

query publicRepositoriesByOrganization($slug: String!) {
  enterprise(slug: $slug) {
    ...enterpriseFragment
  }
}

fragment enterpriseFragment on Enterprise {
  ... on Enterprise{
    name
    organizations(first: 100){
      nodes{
        name
        ... on Organization{
          name
          repositories(privacy: PUBLIC){
            totalCount
          }
        }
      }
    }
  }
}

# Passing our Enterprise Account as a variable
variables {
  "slug": "<enterprise-account-name>"
}

Bei der nächsten GraphQL-Abfrage wird gezeigt, wie schwierig es ist, die Anzahl von public-Repositorys in jeder Organisation abzurufen, ohne die Unternehmenskonten-API zu verwenden. Beachte, dass die Unternehmenskonten-API für GraphQL diese Aufgabe für Unternehmen vereinfacht hat, da du nur eine einzelne Variable anpassen musst. Ersetze <name-of-organization-one> und <name-of-organization-two> usw. durch die Organisationsnamen in deiner Instanz, um diese Abfrage anzupassen.

# Each organization is queried separately
{
  organizationOneAlias: organization(login: "nameOfOrganizationOne") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}

## How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

Separates Abfragen jeder Organisation

query publicRepositoriesByOrganization {
  organizationOneAlias: organization(login: "<name-of-organization-one>") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "<name-of-organization-two>") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}
# How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

Die GraphQL-Abfrage fordert die letzten fünf Protokolleinträge einer Unternehmensorganisation an. Ersetze <org-name> und <user-name>, um diese Abfrage anzupassen.

{
  organization(login: "<org-name>") {
    auditLog(last: 5, query: "actor:<user-name>") {
      edges {
        node {
          ... on AuditEntry {
# Get Audit Log Entry by 'Action'
            action
            actorLogin
            createdAt
# User 'Action' was performed on
           user{
              name
                email
            }
          }
        }
      }
    }
  }
}

Weitere Informationen zu den ersten Schritten mit GraphQL findest du unter Einführung in GraphQL und Tätigen von Aufrufen mit GraphQL.

GraphQL-Felder und -Typen für die Unternehmenskonten-API

Hier findest du eine Übersicht über die neuen Abfragen, Änderungen und schemadefinierten Typen, die mit der Unternehmenskonten-API verwendet werden können.

Weitere Informationen zu den neuen Abfragen, Änderungen und schemadefinierten Typen, die mit der Unternehmenskonten-API verwendet werden können, findest du auf der Randleiste mit den detaillierten GraphQL-Definitionen auf jeder Referenzseite zu GraphQL.

Du kannst auf die Referenzdokumente im GraphQL-Explorer auf GitHub zugreifen. Weitere Informationen findest du unter Verwenden des Explorers. Weitere Informationen wie Authentifizierungs- und Ratenlimitdetails findest du in den Anleitungen.