Verwalten von Unternehmenskonten

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

In diesem Artikel

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 Felder, die mit der Überwachungsprotokoll-API verfügbar sind, findest du unter Schnittstellen.

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 Felder, die mit der Unternehmenskonten-API verfügbar sind, findest du unter Verwalten von Unternehmenskonten.

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

  1. Um dich mit GraphQL zu authentifizieren, musst du ein personal access token aus den Entwicklereinstellungen generieren. Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.

  2. Gewähre deinem personal access token Administratorberechtigungen und Vollzugriff für die Bereiche deines Unternehmens, 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. Wähle das Menü „Auth“ und dann Bearer Token aus. Wenn du zuvor eine andere Authentifizierungsmethode ausgewählt hast, wird das Menü stattdessen mit dieser Methode beschriftet (z. B. „Basic Auth“).

    Screenshot des erweiterten Menüs „Auth“ in Insomnia. Die Menübezeichnung „Auth“ und die Option „Bearer Token“ sind dunkel orange umrandet.

  3. Gib im Feld „TOKEN“ dein personal access token aus einem der vorherigen Schritte ein.

    Screenshot der Authentifizierungseinstellungen unter „Bearer“ in Insomnia. Das Feld „TOKEN“ ist dunkelorange umrandet.

  4. Wähle Headers aus.

    Screenshot der Einstellungsregisterkarten in Insomnia. Die Registerkarte „Headers“ ist dunkelorange umrandet.

  5. Wählen auf der Registerkarte Headers die Option Add aus.

  6. Gib Content-Type in das Feld „Header“ ein.

  7. Gib application/json in das Feld „Value“ ein.

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 Anwendung mithilfe der Enterprise–Konto-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 Erstellen von Aufrufen mit GraphQL.

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

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.