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 uma solicitação de informações para ver todos os novos integrantes da organização adicionados à sua organização. Ou você pode fazer uma mutação ou alteração para convidar um administrador para a sua conta corporativa.

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

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

A API de Log de Auditoria permite que você mantenha cópias dos seus 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 obter uma lista dos campos disponíveis na API do Log de Auditoria, consulte a "interface 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 obter uma lista dos campos disponíveis da API de Contas corprativas, consulte "campos e tipos do GraphQL para a API de Conta corporativa".

Primeiros passos usando o GraphQL para contas corporativas

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

• Efetuando a autenticação com um token de acesso pessoal
• Escolher um cliente do GraphQL ou usar o Explorador do GraphQL
• Configurar a o Insomnia para usar a API do GraphQL

Para alguns exemplos de consulta, veja "Exemplo de consulta usando a API de Contas corporativas".

1. Efetuando a autenticação com seu token de acesso pessoal

1. Para efetuar a autenticação com o GraphQL, você precisa gerar um token de acesso pessoal (PAT) a partir das configurações do desenvolvedor. Para mais informação, consulte "Criando um token de acesso pessoal."

2. Conceda permissões de administrador e controle total ao seu token de acesso pessoal para as áreas do GHES que você gostaria de acessar. Para obter a permissão total para repositórios privados, organizações, equipes, dados de usuário e acesso aos dados de cobrança da empresa e de perfil, recomendamos que você selecione estes escopos para o seu token de acesso pessoal:

   • repo
   • admin:org
   • usuário
   • admin:enterprise

   Os escopos específicos da conta corporativa são:

   • admin:enterprise: Fornece controle total de empresas (inclui manage_billing:enterprise e read:enterprise)
   • manage_billing:enterprise: Lê e grava dados de cobrança da empresa.
   • read:enterprise: Lê dados do perfil empresarial.

3. Copie seu token de acesso pessoal e guarde-o em um lugar seguro até adicioná-lo ao seu cliente do GraphQL.

2. Escolha 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:

• Insomnia
• GraphiQL
• Postman

As próximas etapas usarão o Insomnia.

3. Configurando o Insomnia para usar a API do GraphQL do GitHub com contas corporativas

1. Adicione a URL de base e o método POST ao seu 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 de base segue esta sintaxe:

   • Para a instância de sua empresa: https://<HOST>/api/graphql
   • Para o GitHub Enterprise Cloud: https://api.github.com/graphql

2. Para efetuar a autenticação, abra o menu de opções de autenticação e selecione Token portador. Em seguida, adicione seu token de acesso pessoal que você copiou anteriormente.

   

   

3. Incluir informações do header.

   • Adicione Content-Type como header e application/json como valor.

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

Um exemplo e consulta usando a API de Contas corporativas

Essa consulta do GraphQL solicita o número total de repositórios públicos em cada uma das organizações dos seus aplicativos usando a API de contas corporativas. Para personalizar esta consulta, substitua <enterprise-account-name> pelo slug do slug de instância da sua empresa.

query publicRepositoriesByOrganization {
  organizationOneAlias: organization(login: "<name-of-organization-one>") {
    # Como usar um fragmento
    ...repositories
  }
  organizationTwoAlias: organization(login: "<name-of-organization-two>") {
    ...repositories
  }
  # organizationThreeAlias ... e assim por diante até, digamos, 100
}
# Como definir um fragmento
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

O próximo exemplo de consulta GraphQL mostra como é desafiante recuperar o número de repositórios públicos em cada organização sem usar a API da conta corporativa. 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 esta consulta, substitua <name-of-organization-one> e <name-of-organization-two>, etc. pelos nomes de organização na sua instância.

# Cada organização é consultada separadamente
{
  organizationOneAlias: organization(login: "nameOfOrganizationOne") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
    ...repositories
  }
  # organizationThreeAlias ... e assim por diante até, digamos, 100
}

## Como definir um fragmento
repositórios do fragmento na organização {
  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 esta 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 com GraphQL, consulte "Introdução ao GraphQL" e "Formando 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, mutações e tipos definidos por esquema disponíveis para uso com a API de Contas corporativas, consulte a barra lateral com definições detalhadas do GraphQL a partir 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, consulte "Usando o explorador. Para obter outras informações, como detalhes de autenticação e limite de taxa, confira os guias.