Administrar cuentas empresariales

Acerca de administrar cuentas empresariales con GraphQL

Para ayudarte a monitorear y hacer cambios en tu organización y mantener el cumplimiento, puedes utilizar la API de Cuentas Empresariales y la API de Bitácoras de Auditoría, las cuales se encuentran disponibles únicamente como API de GraphQL.

Los puntos de conexión de cuenta de empresa funcionan tanto para GitHub Enterprise Cloud como para GitHub Enterprise Server.

GraphQL permite solicitar y devolver solo los datos que especifique. Por ejemplo, puede crear una consulta GraphQL o solicitar información para ver los nuevos miembros que se han agregado a su organización. O bien puede realizar una mutación o un cambio para invitar a un administrador a su cuenta empresarial.

Con Audit Log API, puede supervisar si alguien hace lo siguiente:

• Accede a la configuración de la organización o del repositorio.
• Cambia los permisos.
• Agrega o quita usuarios de una organización, un repositorio o un equipo.
• Asciende usuarios a administradores.
• Cambia los permisos de una aplicación de GitHub.

Audit Log API permite mantener copias de los datos de los registros de auditoría. Para las consultas realizadas con la API de Bitácoras de Auditoria, la respuesta de GraphQL puede incluir datos de hasta 90 a 120 días. Para obtener una lista de los campos disponibles con Audit Log API, consulta Interfaces.

Con la API de Cuentas Empresariales puedes:

• Listar y revisar todas las organizaciones y repositorios que pertenecen a tu cuenta empresarial.
• Cambiar la configuración de la cuenta empresarial.
• Configurar políticas para la configuración en tu cuenta empresarial y sus organizaciones.
• Invitar administradores a tu cuenta empresarial.
• Crear nuevas organizaciones en tu cuenta empresarial.

Para obtener una lista de los campos disponibles con la API de cuentas de empresa, consulte Administrar cuentas empresariales.

Comenzando a usar GraphQL para cuentas empresariales

Consulte Uso de clientes de GraphQL para comenzar mediante GraphQL a gestionar las cuentas de su empresa.

Para obtener algunas consultas de ejemplo, consulta Una consulta de ejemplo con Enterprise Accounts API.

1. Autenticarse con el personal access token

1. Para autenticarte con GraphQL, debes generar un personal access token desde los ajustes de desarrollador. Para obtener más información, vea Administración de tokens de acceso personal.

2. Otorgue permisos de administración y control total a personal access token para las áreas de su empresa a las que le gustaría acceder. Para obtener permiso total para repositorios privados, organizaciones, equipos, datos de usuario y acceso a datos de perfil y facturación empresarial, recomendamos que seleccione estos ámbitos para su personal access token:

   • repo
   • admin:org
   • user
   • admin:enterprise

   Los alcances específicos para la cuenta empresarial son: * admin:enterprise: proporciona control total de las empresas (incluye manage_runners:enterprise, manage_billing:enterprise y read:enterprise) * manage_billing:enterprise: lectura y escritura de datos de facturación de la empresa.

   •           `manage_runners:enterprise`: acceso para administrar ejecutores y grupos de ejecutores de empresa de Acciones de GitHub.
     

   •     `read:enterprise`: Lectura de datos del perfil empresarial.
     

3. Copia tu personal access token y mantenlo en un lugar seguro hasta que lo agregues a tu cliente de GraphQL.

2. Elección de un cliente de GraphQL

Te recomendamos utilizar GraphiQL u otro cliente independiente de GraphQL que te permita configurar la URL base.

También podrás considerar utilizar estos clientes de GraphQL: * Insomnia * GraphiQL * Postman

Los siguientes pasos utilizarán Insomnia.

3. Configuración de Insomnia para usar la API GraphQL de GitHub con cuentas empresariales

1. Agregue la URL base y el método POST al cliente de GraphQL. Al usar GraphQL para solicitar información (consultas), cambiar información (mutaciones) o transferir datos mediante la API de GitHub, el método HTTP predeterminado es POST y la dirección URL base sigue esta sintaxis:

   • Para tu instancia empresarial: https://<HOST>/api/graphql
   • Para GitHub Enterprise Cloud: https://api.github.com/graphql
   • Para GitHub Enterprise Cloud con residencia de datos activada: https://api.SUBDOMAIN.ghe.com/graphql

2. Selecciona el menú "Autenticación" y haz clic en Token de portador. Si has seleccionado previamente un método de autenticación diferente, el menú se etiquetará con ese método, como "Autenticación básica", en su lugar.

          ![Captura de pantalla del menú "Autenticación" expandido en Insomnia. La etiqueta de menú, "Autenticación" y la opción "Token de portador" aparecen en naranja oscuro.](/assets/images/developer/graphql/insomnia-bearer-token-option.png)
   

3. En el campo "TOKEN", escribe personal access token de un paso anterior.

          ![Captura de pantalla de la configuración de autenticación "Bearer" en Insomnia. El campo "TOKEN" aparece en naranja oscuro.](/assets/images/developer/graphql/insomnia-base-url-and-pat.png)
   

4. Haz clic en Encabezados.

          ![Captura de pantalla de las pestañas de configuración en Insomnia. La pestaña "Encabezados" está delineada en naranja oscuro.](/assets/images/developer/graphql/json-content-type-header.png)
   

5. En la pestaña Encabezados, haz clic en Agregar.

6. En el campo "encabezado", escribe Content-Type.

7. En el campo Valor, escribe application/json.

Ahora estás listo para comenzar a hacer consultas.

Un ejemplo de consulta utilizando la API de Cuentas Empresariales

Esta consulta de GraphQL solicita la cantidad total de repositorios de public en cada una de las organizaciones del dispositivo mediante Enterprise Accounts API. Para personalizar esta consulta, reemplace <enterprise-account-name> por el identificador de la cuenta de empresa. Por ejemplo, si la cuenta de empresa se encuentra en https://github.com/enterprises/octo-enterprise, reemplace <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>"
}

En la siguiente consulta de GraphQL se muestra lo complicado que es recuperar la cantidad de repositorios de public en cada organización sin usar Enterprise Account API. Nota que la API de Cuentas Empresariales de GraphQL ha hecho esta tarea más simple para las empresas, ya que solo necesitas personalizar una sola variable. Para personalizar esta consulta, reemplace <name-of-organization-one> y <name-of-organization-two>, etc., por los nombres de la organización en la instancia.

# 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
  }
}

Consulta a cada organización por separado

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 de GraphQL solicita las últimas 5 entradas de bitácora para una organización empresarial. Para personalizar esta consulta, reemplace <org-name> y <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 obtener más información sobre cómo empezar con GraphQL, consulte Introducción a GraphQL y Formar llamados con GraphQl.

Campos y tipos de GraphQL para la API de Cuentas Empresariales

Para más información sobre las nuevas consultas, mutaciones y tipos definidos del esquema que están disponibles para su uso con la API de Cuentas Empresariales, consulte la barra lateral con definiciones detalladas de GraphQL desde cualquier página de referencia de GraphQL.

Puede acceder a los documentos de referencia desde los clientes de GraphQL. Para obtener más información, vea Uso de clientes de GraphQL. Para obtener otra información, como la autenticación y los detalles del límite de velocidad, consulte el guides.