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 des comptes 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 Audit Log, 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 Enterprise Accounts, consultez « Gestion des comptes d’entreprise ».

Bien démarrer avec GraphQL pour les comptes d’entreprise

Suivez ces étapes pour commencer à utiliser GraphQL pour gérer vos comptes d’entreprise :

Authentification avec un personal access token
Choix d’un client GraphQL ou utilisation de l’Explorateur GraphQL
Configuration d’Insomnia pour utiliser l’API GraphQL

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 les zones de votre entreprise auxquelles vous souhaitez accéder. Pour des autorisations complètes sur les dépôts privés, les organisations, les équipes et les données utilisateur, et pour l’accès aux données de facturation et de profil d’entreprise, nous vous recommandons de sélectionner ces étendues pour votre 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 :

Les étapes suivantes utilisent Insomnia.

3. Configuration d’Insomnia de façon à 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
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.
Dans le champ « JETON », entrez le personal access token défini lors d’une étape précédente.
Cliquez sur En-têtes.
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 référentiels dans chacune des organisations de votre appliance en utilisant l’API des comptes d’entreprise. 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-enterprisel’emplacement, 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 « Formation d’appels avec GraphQL ».

Types et champs GraphQL pour l’API Enterprise Accounts

Voici une vue d’ensemble des nouvelles requêtes, mutations et types définis par le schéma disponibles pour une utilisation avec 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 de l’Explorateur GraphQL sur GitHub. Pour plus d’informations, consultez « Utilisation d’Explorer ». Pour d’autres informations, telles que des détails sur la limite de débit et l’authentification, consultez les guides.

Gestion des comptes d’entreprise

Dans cet article