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 (incluimanage_runners:enterprise
,manage_billing:enterprise
eread: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
- Para sua instância corporativa:
-
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.