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 Enterprise-Verwaltung.

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. Wählen Sie eine Authentifizierungsmethode aus.

Wir empfehlen, für GraphQL-Vorgänge in Unternehmen, die dies unterstützen, GitHub App zu verwenden. GitHub Apps bieten Sie differenzierte Berechtigungen und kurzlebige Token, ohne sich auf den Besitzer eines personal access tokenUnternehmens zu verlassen. Nicht alle GraphQL-Abfragen und Mutationen für Unternehmen unterstützen GitHub Apps. Verwenden Sie eine personal access token für Vorgänge, die diese nicht unterstützen.

Verwenden eines GitHub App

Registrieren Sie eine GitHub App und wählen Sie die für Ihre Abläufe erforderlichen Unternehmensberechtigungen aus. Siehe Registrieren einer GitHub-App.
Installieren Sie die App für das Unternehmen, das Sie verwalten möchten. Wenn Sie kein Unternehmensinhaber sind, müssen Sie den Unternehmensinhaber bitten, es zu installieren. Siehe Installieren einer GitHub-App in deinem Unternehmen.
Authentifizieren sie sich mit einem Installationszugriffstoken oder einem Benutzerzugriffstoken, je nach Vorgang und ob die App im Auftrag eines Benutzers handeln muss. Die nachstehenden Insomnia-Anweisungen verwenden ein Benutzerzugriffstoken.

Eine Enterprise-Installation gewährt nur Enterprise-Berechtigungen. Der Zugriff auf Organisationen oder Repositorys im Unternehmen wird nicht gewährt. Für Organisations- oder Repositoryvorgänge benötigt die App separate Installationen für die relevanten Organisationen und die entsprechenden Berechtigungen. Nach der Installation in den Organisationen kann Ihre App mit einem Benutzerzugriffstoken in einer GraphQL-Abfrage organisationsübergreifend arbeiten. Installationstoken sind für ein einzelnes Unternehmens- oder Organisationskonto gesperrt und können nicht über Kontogrenzen hinweg verwendet werden.

Verwenden eines personal access token

Verwenden Sie ein personal access token, wenn der benötigte Vorgang GitHub Apps nicht unterstützt wird, oder wenn Sie Automatisierung für den Zugriff auf mehrere Organisationen oder Repositorydaten in einer einzelnen GraphQL-Abfrage erstellen.

Um sich mit GraphQL mit einem personal access token zu authentifizieren, erstellen Sie eines in den Entwicklereinstellungen. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken.
Gewähren Sie Ihrem personal access token Administrator- und Vollzugriffsrechte für die Bereiche Ihres Unternehmens, auf die Sie zugreifen möchten. Für den vollständigen Zugriff auf private Repositories, Organisationen, Teams, Benutzerdaten sowie Abrechnungs- und Profildaten von Unternehmen empfehlen wir, für Ihre personal access token diese Berechtigungsumfänge auszuwählen:
- 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 Enterprise-Abrechnungsdaten.
- read:enterprise: Unternehmensprofildaten lesen.
Kopieren Sie Ihre Datei personal access token , und bewahren Sie sie an einem sicheren Ort auf, bis Sie sie ihrem GraphQL-Client hinzufügen.

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. 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

Mit einem GitHub App authentifizieren

In diesem Verfahren wird der OAuth 2.0-Autorisierungscodefluss verwendet, um ein GitHub AppBenutzerzugriffstoken und kein Installationszugriffstoken abzurufen.

Legen Sie in den Einstellungen Ihrer App die Rückruf-URL auf http://localhost. Dies muss genau mit der Umleitungs-URL übereinstimmen, die Sie in Insomnia verwenden.
Kopieren Sie die Client-ID Ihrer App, nicht die App-ID. Generieren und kopieren Sie ein Clientgeheimnis. Schützen Sie das Geheimnis, und geben Sie es nicht in Screenshots oder Quellcode frei. Dieser Fluss verwendet nicht den privaten Schlüssel der App.
Wählen Sie in Insomnia die Registerkarte Auth und dann OAuth 2.0 aus. Wenn Sie zuvor eine andere Authentifizierungsmethode ausgewählt haben, wird die Registerkarte möglicherweise mit dieser Methode bezeichnet.

Konfigurieren Sie diese Einstellungen mit den Anmeldeinformationen Ihrer eigenen App.

Setting	Wert
Enabled	✔️
Art des Zuschusses	Autorisierungscode
Autorisierungs-URL	`https://github.com/login/oauth/authorize`
Zugriffstoken-URL	`https://github.com/login/oauth/access_token`
Client-ID	Client-ID Ihrer App
Geheimer Clientschlüssel	Das Client-Secret Ihrer App
PKCE verwenden

Ausgewählt | | | | Codeabfrage-Methode | SHA-256 | | | | Umleitungs-URL | http://localhost | | Standardbrowser verwenden | Lassen Sie das Kontrollkästchen deaktiviert, es sei denn, in Ihrem Unternehmen ist SSO aktiviert, was im eingebetteten Browser von Insomnia fehlschlagen kann. Wenn SSO aktiviert ist, aktivieren Sie dieses Kontrollkästchen, und folgen Sie den Anweisungen zum Aktualisieren der Umleitungs-URL Ihrer App. | | Umfang | Lassen Sie dieses Feld leer. GitHub Apps Verwenden Sie Berechtigungen aus der App-Registrierung, nicht OAuth-Berechtigungen. |

Wenn Sie GitHub Enterprise Cloud mit Datenresidenz verwenden, ersetzen Sie https://github.com in beiden OAuth-URLs durch https://SUBDOMAIN.ghe.com, wobei SUBDOMAIN die Unterdomäne Ihres Unternehmens ist. Verwenden Sie die Web-URL, nicht den api.SUBDOMAIN.ghe.com Hostnamen.

Klicken Sie auf Token abrufen, melden Sie sich an, und autorisieren Sie die App als Benutzer mit den erforderlichen Unternehmensberechtigungen. Das Benutzerzugriffstoken ist auf die Berechtigungen und Ressourcen beschränkt, auf die sowohl der Benutzer als auch die App zugreifen können. Insomnia verwendet das abgerufene Token für Ihre Anfragen.

Weitere Informationen finden Sie unter Generieren eines Benutzerzugriffstokens für eine GitHub App.

Mit einem personal access token authentifizieren

Wenn Sie stattdessen ein personal access token verwenden, konfigurieren Sie die Bearerauthentifizierung.

Wählen Sie das Menü "Authentifizierung" aus, und klicken Sie auf "Bearertoken". Wenn du zuvor eine andere Authentifizierungsmethode ausgewählt hast, wird das Menü stattdessen mit dieser Methode beschriftet (z. B. „Basic Auth“).
Geben Sie im Feld "TOKEN" Ihren personal access token aus einem früheren Schritt ein.

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

Inhaltstyp festlegen

Legen Sie nach dem Konfigurieren der Authentifizierungsmethode den Inhaltstyp der Anforderung fest.

Wähle Headers aus.

Screenshot der Einstellungsregisterkarten in Insomnia. Der Tab „Headers“ ist dunkelorange umrandet.

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