# Gerenciar contas corporativas

Você pode gerenciar sua conta corporativa e as organizações que ela possui com a API 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 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 [Administração de empresas](/pt/enterprise-server@3.22/graphql/reference/enterprise-admin#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 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](/pt/enterprise-server@3.22/graphql/guides/managing-enterprise-accounts#graphql-fields-and-types-for-the-enterprise-accounts-api).

## Primeiros passos com o uso do GraphQL para contas empresariais

Consulte [Como usar clientes do GraphQL](/pt/enterprise-server@3.22/graphql/guides/using-graphql-clients) 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](#an-example-query-using-the-enterprise-accounts-api).

### 1. Faça a autenticação com sua personal access token

1. Para se autenticar com o GraphQL, você precisa gerar um personal access token nas configurações do desenvolvedor. Para obter mais informações, consulte [Gerenciar seus tokens de acesso pessoal](/pt/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).

2. Conceda permissões de administrador e controle total às áreas personal access token da sua empresa que você gostaria de acessar. Para obter permissão total para repositórios privados, organizações, equipes, dados do usuário e acesso a dados de cobrança empresarial e de perfil, recomendamos que você selecione os seguintes escopos para o seu 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`: ler e gravar 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 mantenha-o em um local seguro até adicioná-lo ao cliente 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](https://support.insomnia.rest/article/176-graphql-queries)
* [GraphiQL](https://www.gatsbyjs.org/docs/running-queries-with-graphiql/)
* [Postman](https://learning.getpostman.com/docs/postman/sending_api_requests/graphql/)

As próximas etapas usarão Insomnia.

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

1. 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`

2. 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)

1. No campo "TOKEN", insira seu personal access token obtido em 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)

1. 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)

1. Na guia **Cabeçalhos**, clique em **Adicionar**.
2. No campo "cabeçalho", insira `Content-Type`.
3. 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`.

```graphql
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.

```graphql
# 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

```graphql
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>`.

```graphql
{
  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](/pt/enterprise-server@3.22/graphql/guides/introduction-to-graphql) e [Realizar chamadas com o GraphQL](/pt/enterprise-server@3.22/graphql/guides/forming-calls-with-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](/pt/enterprise-server@3.22/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](/pt/enterprise-server@3.22/graphql/guides/using-graphql-clients).
Para obter outras informações, como detalhes de autenticação e limite de taxa, confira o [guides](/pt/enterprise-server@3.22/graphql/guides).