Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Esta versão do GitHub Enterprise foi descontinuada em 2023-01-18. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Gerenciar contas corporativas

Você pode gerenciar sua conta corporativa e as organizações detêm com a API do GraphQL.

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 "interface do AuditEntry".

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 Enterprise, confira "Campos e tipos do GraphQL para a API de Contas Enterprise".

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

  1. 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 "Como criar um personal access token".

  2. Conceda permissões de administrador e controle completo ao personal access token para as áreas do GHES 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.
  3. 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

  1. 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
  2. Para se autenticar, abra o menu de opções de autenticação e selecione Token de portador. Depois, adicione o personal access token que você copiou anteriormente.

    Opções de permissões para o personal access token

    Opções de permissões para o personal access token

  3. Incluir informações do header.

    • Adicione Content-Type como o cabeçalho e application/json como o valor. Cabeçalho padrão Cabeçalho com valor de visualização para a API de Log de Auditoria

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 repositórios public 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 como começar a usar o GraphQL, confira "Introdução ao GraphQL" e "Como formar chamadas com o GraphQL".

Campos e tipos do GraphQL para a API de Contas corporativas

Aqui está uma visão geral das novas consultas, mutações e tipos definidos por esquema disponíveis para uso com 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 "Como usar o Explorer". Para obter outras informações, como detalhes de autenticação e limite de taxa, confira os guias.