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 endpoints 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 por um período de até 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 empresarial.
Criar novas organizações na sua conta corporativa.

Para obter uma lista dos campos disponíveis com a API contas corporativas, consulte Gerenciar contas corporativas.

Primeiros passos com o uso do GraphQL para contas empresariais

Consulte Como usar clientes do GraphQL para começar a usar o GraphQL para gerenciar suas contas corporativas.

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, consulte 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 corporativos do GitHub Actions e grupos de executores. * 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: * Insomnia * GraphiQL * Postman

As próximas etapas usarão Insomnia.

3. Configurar o Insomnia para usar a API GraphQL do GitHub com contas empresariais

Adicione a URL base e o método POST ao cliente GraphQL. Ao usar o GraphQL para solicitar informações (consultas), alterar informações (mutações) ou transferir dados usando a API 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 GitHub Enterprise Cloud: https://api.github.com/graphql
- Para GitHub Enterprise Cloud com Residência de Dados: https://api.SUBDOMAIN.ghe.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".

       ![Captura de tela do menu "Autenticação" expandido em Insônia. O rótulo de menu "Auth" e a opção "Bearer Token" são destacados em laranja escuro.](/assets/images/developer/graphql/insomnia-bearer-token-option.png)

No campo "TOKEN", insira seu personal access token de uma etapa anterior.

       ![Captura de tela das configurações de autenticação "Bearer" em Insomnia. O campo "TOKEN" é descrito em laranja escuro.](/assets/images/developer/graphql/insomnia-base-url-and-pat.png)

Clique em Cabeçalhos.

       ![Captura de tela das guias de configurações em Insônia. A guia "Cabeçalhos" está descrita em laranja escuro.](/assets/images/developer/graphql/json-content-type-header.png)

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 de consulta usando a API de Contas Empresariais

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 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 com o GraphQL, consulte 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 os documentos de referência a partir dos clientes GraphQL. Para obter mais informações, consulte Como usar clientes do GraphQL. Para obter outras informações, como detalhes de autenticação e limite de taxa, confira o guides.

Neste artigo