Administrar cuentas empresariales

Puedes administrar tu cuenta empresarial y las organizaciones que le pertenecen con la API de GraphQL.

En este artículo

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.

Las terminales de cuenta empresarial funcionan tanto para GitHub Enterprise Cloud y 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 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.
  • Promueve usuarios a administradores.
  • Cambia los permisos de una aplicación de GitHub Apps.

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, consulta Administrar cuentas empresariales.

Comenzar a utilizar GraphQL para cuentas empresariales

Sigue estos pasos para comenzar a utilizar GraphQL para administrar tus cuentas empresariales:

  • Autenticación con un personal access token
  • Elegir un cliente de GraphQL o utilizar el Explorador de GraphQL
  • Configurar Insomnia para utilizar la API de GraphQL

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 la configuración de desarrollador. Para más información, consulta Administración de tokens de acceso personal.

  2. Concede permisos de control total a tu personal access token para las áreas de la empresa a las que quieras acceder. Para tener permiso total en los repositorios privados, organizaciones, equipos, datos de usuario y acceso a la facturación empresarial y datos de perfil, te recomendamos que selecciones estos ámbitos para tu 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.
    • read:enterprise: lectura de datos del perfil de empresa.

  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:

Los siguientes pasos utilizarán Insomnia.

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

  1. Agregue la URL base y el método POST al cliente de GraphQL. Cuando use 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 URL base sigue esta sintaxis:

    • Para la instancia empresarial: https://<HOST>/api/graphql
    • Para GitHub Enterprise Cloud: https://api.github.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.

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

    Captura de pantalla de la configuración de autenticación "Portador" en Insomnia. El campo "TOKEN" aparece en naranja oscuro.

  4. Haz clic en Encabezados.

    Captura de pantalla de las pestañas de configuración en Insomnia. La pestaña "Encabezados" aparece en naranja oscuro.

  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 más información sobre cómo empezar a usar GraphQL, consulta 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 as nuevas consultas, mutaciones y tipos definidos por el esquema disponibles para usar con Enterprise Accounts API, vea la barra lateral con definiciones detalladas de GraphQL desde cualquier página de referencia de GraphQL.

Puedes acceder a los documentos de referencia desde dentro del explorador de GraphQL en GitHub. Para más información, consulta Utilizar el Explorador. Para obtener otra información, como los detalles de autenticación y límite de frecuencia, consulte las guías.