Verwalten von Unternehmenskonten

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
Ändert Berechtigungen.
Benutzer in einer Organisation, einem Repository oder einem Team hinzufügt oder daraus entfernt.
Benutzer zum Administrator heraufstuft.
Ändert die Berechtigungen einer GitHub App.

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 Enterprise-Konten-API verfügbar sind, finden Sie unter Verwalten von Unternehmenskonten.

Einführung in die Verwendung von GraphQL für Unternehmenskonten

Um zu beginnen, wie Sie mit GraphQL Ihre Enterprise-Konten verwalten, siehe Verwenden von GraphQL-Clients.

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

1. Authentifizieren Sie sich mit Ihrem personal access token

Um dich mit GraphQL zu authentifizieren, musst du ein personal access token aus den Entwicklereinstellungen generieren. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken.
Erteilen Sie Administrator- und Vollzugriffsberechtigungen für Ihre personal access token für Bereiche Ihres Unternehmens, auf die Sie zugreifen möchten. 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: Unternehmensabrechnungsdaten lesen und schreiben
- ```
          `manage_runners:enterprise`: Zugriff zur Verwaltung von Unternehmens-Runnern und -Runnergruppen von GitHub Actions
```
- ```
    `read:enterprise`: Unternehmensprofildaten lesen.
```
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: * Insomnia * GraphiQL * Postman

In den nächsten Schritten wird Insomnia verwendet.

3. Einrichtung von Insomnia für die Verwendung der GitHub GraphQL-API mit Unternehmenskonten

Füge dem GraphQL-Client die Basis-URL und die POST-Methode hinzu. Wenn Sie GraphQL verwenden, um Informationen (Abfragen), Änderungsinformationen (Mutationen) anzufordern oder Daten mithilfe der GitHub-API zu übertragen, ist die standardmäßige 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
- Für GitHub Enterprise Cloud mit Datenresidenz: https://api.SUBDOMAIN.ghe.com/graphql

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.](/assets/images/developer/graphql/insomnia-bearer-token-option.png)

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.](/assets/images/developer/graphql/insomnia-base-url-and-pat.png)

Wähle Headers aus.

       ![Screenshot der Einstellungsregisterkarten in Insomnia. Der Tab „Headers“ ist dunkelorange umrandet.](/assets/images/developer/graphql/json-content-type-header.png)

Wählen auf der Registerkarte Headers die Option Add aus.
Gib Content-Type in das Feld „Header“ ein.
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. Ersetzen Sie <enterprise-account-name> durch den Bezeichner Ihres Unternehmenskontos, um diese Abfrage anzupassen. Wenn sich Ihr Unternehmenskonto beispielsweise unter https://github.com/enterprises/octo-enterprise befindet, ersetzen Sie <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
  }
}

Jede Organisation einzeln abfragen

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 zur Einführung in GraphQL finden Sie 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.

Sie können über die GraphQL-Clients auf die Referenzdokumente zugreifen. Weitere Informationen finden Sie unter Verwenden von GraphQL-Clients. Weitere Informationen, z. B. Authentifizierungs- und Zinslimitdetails, finden Sie im guides.

In diesem Artikel