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 Administración empresarial.

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. Elegir un método de autenticación

Se recomienda usar un/una GitHub App para operaciones empresariales de GraphQL que lo admitan. GitHub Apps proporcionar permisos específicos y tokens de corta duración sin depender de un propietario de empresa personal access token. No todas las consultas y mutaciones de GraphQL empresariales admiten GitHub Apps. Use un personal access token para las operaciones que no lo admitan.

Uso de un GitHub App

Registre una GitHub App y seleccione los permisos de empresa necesarios para las operaciones. Consulte Registro de una aplicación de GitHub.
Instale la aplicación en la organización que desea administrar. Si no es propietario de la empresa, deberá pedir al propietario de la empresa que lo instale. Consulte Instalación de una aplicación de GitHub en tu empresa.
Autentíquese con un token de acceso de instalación o un token de acceso de usuario, en función de la operación y si la aplicación debe actuar en nombre de un usuario. Las instrucciones siguientes de Insomnia usan un token de acceso de usuario.

Una instalación empresarial solo concede permisos empresariales. No concede acceso a organizaciones o repositorios en la empresa. Para las operaciones de organización o repositorio, la aplicación necesita instalaciones independientes en las organizaciones pertinentes y los permisos adecuados. Una vez instalada en las organizaciones, la aplicación puede operar en todas ellas en una consulta de GraphQL mediante un token de acceso de usuario. Los tokens de instalación se bloquean en una sola cuenta de empresa u organización y no se pueden usar entre cuentas.

Uso de un personal access token

Use un personal access token si la operación que necesita no admite GitHub Apps, o si va a crear automatización para acceder a datos de varias organizaciones o repositorios en una sola consulta GraphQL.

Para autenticarse en GraphQL con un personal access token, cree uno en la configuración del desarrollador. Para obtener más información, vea Administración de tokens de acceso personal.
Conceda permisos de administrador y control total a las personal access token áreas de su empresa a las que desea acceder. Para obtener permiso total para repositorios privados, organizaciones, equipos, datos de usuario y acceso a datos de perfil y facturación empresarial, se recomienda seleccionar estos ámbitos para 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: leer y escribir datos de facturación empresarial.
- read:enterprise: Lectura de datos del perfil empresarial.
Copie su personal access token y guárdelo en un lugar seguro hasta que lo añada a su cliente 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 la API GraphQL de GitHub con cuentas empresariales

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

Autentícate con un GitHub App

Este procedimiento usa el flujo de código de autorización de OAuth 2.0 para obtener un GitHub Apptoken de acceso de usuario, no un token de acceso de instalación.

En la configuración de la aplicación, establezca La dirección URL de devolución de llamada en http://localhost. Esto debe coincidir exactamente con la dirección URL de redireccionamiento que usa en Insomnia.
Copie el ID de cliente de la aplicación, no su identificador de aplicación. Genere y copie un secreto del cliente. Mantenga el secreto seguro y no lo comparta en capturas de pantalla o código fuente. Este flujo no usa la clave privada de la aplicación.
En Insomnia, seleccione la pestaña Auth y, a continuación, seleccione OAuth 2.0. Si ha seleccionado previamente un método de autenticación diferente, es posible que la pestaña se etiquete con ese método.

Configure estas opciones con las credenciales de su propia aplicación.

Setting	Value
Enabled	✔️
Tipo de subvención	Código de autorización
Dirección URL de autorización	`https://github.com/login/oauth/authorize`
URL del token de acceso	`https://github.com/login/oauth/access_token`
Id de cliente	ID de cliente de tu aplicación
Secreto del cliente	Secreto de cliente de tu aplicación
Usar PKCE

Seleccionado | | | | Método de desafío de código | SHA-256 | | | | URL de redirección | http://localhost | | Uso del navegador predeterminado | Deje desactivado, a menos que su empresa tenga el inicio de sesión único habilitado, lo que puede producir un error en el explorador insertado de Insomnia. Si tiene SSO habilitado, active esta casilla y siga las instrucciones para actualizar la dirección URL de redireccionamiento de la aplicación. | | Ámbito | Dejar en blanco. GitHub Apps usa permisos del registro de la aplicación, no de los ámbitos de OAuth. |

Si usa GitHub Enterprise Cloud con residencia de datos, reemplace https://github.com en ambas direcciones URL de OAuth por https://SUBDOMAIN.ghe.com, donde SUBDOMAIN es el subdominio de la empresa. Use la dirección URL web, no el nombre de api.SUBDOMAIN.ghe.com host.

Haga clic en Obtener tokens, inicie sesión y autorice la aplicación como usuario con los permisos de empresa necesarios. El token de acceso de usuario se limita a los permisos y recursos a los que el usuario y la aplicación pueden acceder. Insomnia usa el token capturado para sus solicitudes.

Para obtener más información, vea Generación de un token de acceso de usuario para una aplicación de GitHub.

Autentícate con un personal access token

Si usa un personal access token en su lugar, configure la autenticación de portador.

Seleccione el menú Auth y haga clic en Bearer Token. 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.
En el campo "TOKEN", introduzca su personal access token obtenido en un paso anterior.

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

Establecer el tipo de contenido

Después de configurar el método de autenticación, establezca el tipo de contenido de la solicitud.

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.

En la pestaña Encabezados, haz clic en Agregar.
En el campo "encabezado", escribe Content-Type.
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.

En este artículo