Gerenciar contas corporativas

Sobre o gerenciamento de contas corporativas com o GraphQL

Para ajudá-lo a monitorar e fazer alterações nas suas organizações e manter a conformidade, você pode usar a API de Contas corporativas e a API de log de auditoria, que estão disponíveis apenas como APIs do GraphQL.

Os pontos finais da conta corporativa funcionam tanto para o GitHub Enterprise Cloud quanto para o GitHub Enterprise Server.

O GraphQL permite que você solicite e retorne apenas os dados especificados. Por exemplo, você pode criar uma consulta GraphQL ou solicitar informações para ver todos os novos membros da organização adicionados à sua organização. Ou você pode fazer uma mutação ou alteração para convidar um administrador para sua conta corporativa.

Com a API do Log de Auditoria, você pode monitorar quando alguém:

Acessa as configurações de sua organização ou repositório.
Altera as permissões.
Adiciona ou remove usuários em uma organização, repositório ou equipe.
Promove os usuários a administrador.
Altera as permissões de um aplicativo GitHub.

A API do Log de Auditoria permite que você mantenha cópias dos dados do log de auditoria. Para consultas feitas com a API do Log de Auditoria, a resposta do GraphQL pode incluir dados de 90 a 120 dias. Para ver uma lista dos campos disponíveis na API de Log de Auditoria, confira a "Interfaces".

Com a API de Contas corporativas, você pode:

Listar e revisar todas as organizações e repositórios que pertencem à conta corporativa.
Alterar configurações da conta empresarial.
Configurar políticas para configurações na conta corporativa e em suas organizações.
Convidar os administradores para a sua conta corporativa.
Criar novas organizações na sua conta corporativa.

Para ver uma lista dos campos disponíveis na API de contas corporativas, confira "Gerenciar contas corporativas".

Primeiros passos usando o GraphQL para contas corporativas

Siga estes passos para começar a usar o GraphQL para gerenciar as suas contas corporativas:

Autenticação com um personal access token
Escolher um cliente do GraphQL ou usar o Explorador do GraphQL
Configurar a o Insomnia para usar a API do GraphQL

Para ver alguns exemplos de consultas, confira "Um exemplo de consulta que usa a API de Contas Enterprise".

1. Autenticar com o personal access token

Para fazer a autenticação com o GraphQL, você precisa gerar um personal access token por meio das configurações do desenvolvedor. Para obter mais informações, confira "Gerenciar seus tokens de acesso pessoal".
Conceda permissões de administrador e controle completo ao personal access token para as áreas da sua corporação que você quer acessar. Para obter a permissão completa a repositórios privados, organizações, equipes, dados de usuário e acesso aos dados de cobrança e de perfil da empresa, recomendamos que você selecione estes escopos para o personal access token:
- repo
- admin:org
- user
- admin:enterprise
Os escopos específicos da conta corporativa são:
- admin:enterprise: fornece controle completo das empresas (inclui manage_runners:enterprise, manage_billing:enterprise e read:enterprise)
- manage_billing:enterprise: lê e grava dados de cobrança da empresa.
- manage_runners:enterprise: acesso para gerenciar executores da empresa e grupos de executores do GitHub Actions.
- read:enterprise: lê os dados de perfil da empresa.
Copie o personal access token e cole-o em um lugar seguro até adicioná-lo ao cliente do GraphQL.

2. Escolher um cliente do GraphQL

Recomendamos que você use o GraphiQL ou outro cliente autônomo do GraphQL que permite configurar a URL de base.

Você também pode considerar o uso destes clientes do GraphQL:

As próximas etapas usarão o Insomnia.

3. Como configurar o Insomnia para usar a API do GraphQL no GitHub com as contas corporativas

Adicione a URL base e POST o método ao cliente do GraphQL. Ao usar o GraphQL para solicitar informações (consultas), alterar informações (mutações) ou transferir dados usando a API do GitHub, o método HTTP padrão é POST e a URL base segue esta sintaxe:
- Para sua instância corporativa: https://<HOST>/api/graphql
- Para o GitHub Enterprise Cloud: https://api.github.com/graphql
Selecione o menu "Autenticação" e clique em Token de Portador. Se você tiver selecionado anteriormente um método de autenticação diferente, o menu será rotulado com esse método, como "Autenticação Básica".
No campo "TOKEN", insira seu personal access token de uma etapa anterior.
Clique em Cabeçalhos.
Na guia Cabeçalhos, clique em Adicionar.
No campo "cabeçalho", insira Content-Type.
No campo "valor", insira application/json.

Agora você está pronto para começar a fazer consultas.

Um exemplo e consulta usando a API de Contas corporativas

Esta consulta do GraphQL solicita o número total de public repositórios em cada uma das organizações do seu dispositivo usando a API de Contas Enterprise. Para personalizar essa consulta, substitua <enterprise-account-name> pelo identificador da sua conta corporativa. Por exemplo, se a sua conta corporativa estiver localizada em https://github.com/enterprises/octo-enterprise, substitua <enterprise-account-name> por 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>"
}

O próximo exemplo de consulta GraphQL mostra como é complexo recuperar o número de repositórios public em cada organização sem usar a API de Contas Enterprise. Observe que a API de Contas corporativas do GraphQL simplificou esta tarefa para empresas, pois você só precisa personalizar uma única variável. Para personalizar essa consulta, substitua <name-of-organization-one> e <name-of-organization-two> etc. pelos nomes da organização na sua instância.

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

Consulte cada organização separadamente

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

Esta consulta do GraphQL solicita as últimas 5 entradas de registro para uma organização corporativa. Para personalizar essa consulta, substitua <org-name> e <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
            }
          }
        }
      }
    }
  }
}

Para obter mais informações sobre introdução ao GraphQL, confira "Introdução ao GraphQL" e "Realizar chamadas com o GraphQL".

Campos e tipos do GraphQL para a API de Contas corporativas

Para obter mais detalhes sobre as novas consultas, as mutações e os tipos definidos por esquema disponíveis para uso na API de Contas Enterprise, confira a barra lateral com definições detalhadas do GraphQL de qualquer página de referência do GraphQL.

Você pode acessar a documentação de referência de no explorador do GraphQL no GitHub. Para obter mais informações, confira "Usar o Explorador". Para obter outras informações, como detalhes de autenticação e limite de taxa, confira os guias.

Neste artigo