Gestion des comptes d’entreprise

À propos de la gestion des comptes d’entreprise avec GraphQL

Pour vous aider à superviser et à apporter des modifications dans vos organisations et à maintenir la conformité, vous pouvez utiliser l’API Enterprise Accounts et l’API Audit Log, qui sont disponibles uniquement en tant qu’API GraphQL.

Les points de terminaison de compte d’entreprise fonctionnent à la fois pour GitHub Enterprise Cloud et pour GitHub Enterprise Server.

GraphQL vous permet de demander et de retourner uniquement les données que vous spécifiez. Par exemple, vous pouvez créer une requête GraphQL ou demander des informations pour afficher tous les nouveaux membres de l’organisation ajoutés à votre organisation. Ou vous pouvez effectuer une mutation, ou un changement, pour inviter un administrateur à votre compte d’entreprise.

Avec l’API Audit Log, vous pouvez surveiller quand quelqu’un :

Accède aux paramètres de votre organisation ou de votre référentiel.
Modifie les autorisations.
Ajoute ou supprime des utilisateurs dans une organisation, un référentiel ou une équipe.
Promeut les utilisateurs en administrateurs.
Modifie les autorisations d’une application GitHub.

L’API Audit Log vous permet de conserver des copies de vos données de journal d’audit. Pour les requêtes effectuées avec l’API Audit Log, la réponse GraphQL peut inclure des données pendant 90 à 120 jours. Pour obtenir la liste des champs disponibles avec l’API de journal d'audit, consultez Interfaces.

Avec l’API Enterprise Accounts, vous pouvez :

Lister et passer en revue toutes les organisations et dépôts qui appartiennent à votre compte d’entreprise.
Modifier les paramètres de compte d’entreprise.
Configurer des stratégies pour les paramètres sur votre compte d’entreprise et ses organisations.
Inviter des administrateurs à votre compte d’entreprise.
Créer de nouvelles organisations dans votre compte d’entreprise.

Pour obtenir la liste des champs disponibles avec l’API Comptes d’entreprise, consultez Gestion des comptes d’entreprise.

Commencer en utilisant GraphQL pour les comptes d'entreprise

Consultez Utilisation des clients GraphQL pour commencer à utiliser GraphQL et gérer vos comptes d'entreprise.

Pour obtenir des exemples de requêtes, consultez Exemple de requête à l’aide de l’API Enterprise Accounts.

1. Authentifiez-vous avec votre personal access token.

Pour vous authentifier auprès de GraphQL, vous devez générer un personal access token à partir des paramètres du développeur. Pour plus d’informations, consultez Gestion de vos jetons d’accès personnels.
Accordez des autorisations d'administrateur et de contrôle total à votre personal access token pour accéder aux zones de votre entreprise que vous souhaitez. Pour obtenir une autorisation complète pour les dépôts privés, les organisations, les équipes, les données utilisateur et l'accès aux données de facturation et de profil d’entreprise, nous vous recommandons de sélectionner ces périmètres pour vos personal access token :
- repo
- admin:org
- user
- admin:enterprise
Les étendues propres au compte d’entreprise sont les suivantes : * admin:enterprise : donne le contrôle total des entreprises (y compris manage_runners:enterprise, manage_billing:enterprise et read:enterprise) * manage_billing:enterprise : lire et écrire des données de facturation d'entreprise.
- ```
          `manage_runners:enterprise` : accès pour gérer les exécuteurs et groupes d’exécuteurs d’entreprise GitHub Actions.
```
- ```
    `read:enterprise` : lire les données de profil d’entreprise.
```
Copiez votre personal access token et conservez-le dans un endroit sécurisé jusqu’à ce que vous l’ajoutiez à votre client GraphQL.

2. Choisir un client GraphQL

Nous vous recommandons d’utiliser GraphiQL ou un autre client GraphQL autonome qui vous permet de configurer l’URL de base.

Vous pouvez également envisager d’utiliser ces clients GraphQL : * Insomnia * GraphiQL * Postman

Les étapes suivantes utilisent Insomnia.

3. Configurer Insomnia pour utiliser l'API GraphQL GitHub avec des comptes d'entreprise

Ajoutez l’URL de base et la méthode POST à votre client GraphQL. Lorsque vous utilisez GraphQL pour demander des informations (requêtes), modifier des informations (mutations) ou transférer des données à l’aide de l’API GitHub, la méthode HTTP par défaut est POST et l’URL de base suit cette syntaxe :
- Pour votre instance d’entreprise : https://<HOST>/api/graphql
- Pour GitHub Enterprise Cloud : https://api.github.com/graphql
- Pour GitHub Enterprise Cloud avec résidence des données : https://api.SUBDOMAIN.ghe.com/graphql

Sélectionnez le menu « Auth » et cliquez sur Jeton du porteur. Si vous avez précédemment sélectionné une autre méthode d’authentification, le menu est étiqueté avec cette méthode, par exemple « Authentification de base », à la place.

       ![Capture d’écran du menu « Auth » développé dans Insomnia. L’étiquette de menu « Auth » et l’option « Jeton du porteur » sont présentées en orange foncé.](/assets/images/developer/graphql/insomnia-bearer-token-option.png)

Dans le champ « JETON », entrez le personal access token obtenu lors d’une étape précédente.

       ![Capture d’écran des paramètres d’authentification « Porteur » dans Insomnia. Le champ « JETON » est indiqué en orange foncé.](/assets/images/developer/graphql/insomnia-base-url-and-pat.png)

Cliquez sur En-têtes.

       ![Capture d’écran des onglets de paramètres dans Insomnia. L’onglet « En-têtes » est présenté en orange foncé.](/assets/images/developer/graphql/json-content-type-header.png)

Sous l’onglet En-têtes, cliquez sur Ajouter.
Dans le champ « en-tête », entrez Content-Type.
Dans le champ « value », entrez application/json.

Maintenant, vous êtes prêt à effectuer des requêtes.

Exemple de requête utilisant l’API Enterprise Accounts

Cette requête GraphQL demande le nombre total de public dépôts dans chacune des organisations de votre appliance à l’aide de l’API Enterprise Accounts. Pour personnaliser cette requête, remplacez <enterprise-account-name> par le handle de votre compte d’entreprise. Par exemple, si votre compte d’entreprise se trouve à https://github.com/enterprises/octo-enterprise, remplacez <enterprise-account-name> par 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>"
}

L’exemple de requête GraphQL suivant montre combien il est difficile de récupérer le nombre de référentiels public dans chaque organisation sans utiliser l’API Enterprise Accounts. Notez que l’API GraphQL Enterprise Accounts simplifie cette tâche pour les entreprises, car vous n’avez besoin de personnaliser qu’une seule variable. Pour personnaliser cette requête, remplacez <name-of-organization-one> et <name-of-organization-two>, etc. par les noms d’organisation de votre instance.

# 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
  }
}

Interroger chaque organisation séparément

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

Cette requête GraphQL demande les cinq dernières entrées de journal pour une organisation d’entreprise. Pour personnaliser cette requête, remplacez <org-name> et <user-name>.

{
  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
            }
          }
        }
      }
    }
  }
}

Pour plus d’informations sur la prise en main de GraphQL, consultez Présentation de GraphQL et Création d’appels avec GraphQL.

Types et champs GraphQL pour l’API Enterprise Accounts

Pour plus d’informations sur les nouvelles requêtes, mutations et types définis par schéma disponibles pour une utilisation avec l’API Enterprise Accounts, consultez la barre latérale où figurent des définitions GraphQL détaillées à partir de n’importe quelle page de référence GraphQL.

Vous pouvez accéder aux documents de référence à partir des clients GraphQL. Pour plus d’informations, consultez Utilisation des clients GraphQL. Pour d’autres informations, telles que les détails de la limite d’authentification et de débit, consultez la guides.

Dans cet article