Uso de la API de registro de auditoría para la empresa

Aprenda a recuperar eventos empresariales mediante programación con la API de REST.

¿Quién puede utilizar esta característica?

Enterprise owners

En este artículo

Note

Los webhooks pueden ser una buena alternativa al registro de auditoría o al sondeo de API para determinados casos de uso. Los webhooks son una manera de que GitHub notifique al servidor cuándo se producen eventos específicos para un repositorio, una organización o una empresa. En comparación con la API o la búsqueda en el registro de auditoría, los webhooks pueden ser más eficaces si solo deseas descubrir (y, posiblemente, registrar) cuándo se producen determinados eventos en tu empresa, organización o repositorio. Consulta Documentación de webhooks.

Mantener el cumplimiento y proteger la propiedad intelectual con puntos de conexión relacionados con el registro de auditoría. Consulta Puntos de conexión de API de REST para registros de auditoría de empresa y Puntos de conexión de API REST para organizaciones.

Para obtener más información sobre los eventos específicos a los que puede acceder a través de los puntos de conexión de registro de auditoría, consulte los artículos siguientes.

Detalles del registro de auditoría

El registro de auditoría muestra los eventos que desencadenan las actividades que afectan a la empresa en los últimos 180 días. La bitácora de auditoría retiene eventos de Git por siete días.

De forma predeterminada, solo se muestran los eventos de los últimos tres meses. Para ver eventos anteriores, debe especificar un intervalo de fechas con el parámetro created. Consulta Entender la sintaxis de búsqueda.

Las marcas de tiempo y los campos de fecha de la respuesta de la API se miden en milisegundos desde la época UTC.

Puedes usar el ámbito read:audit_log para acceder al registro de auditoría mediante la API.

Límite de frecuencia

Cada punto de conexión de API de registro de auditoría tiene un límite de velocidad de 1750 consultas por hora para una combinación determinada de usuario y dirección IP. Para evitar la limitación de velocidad, las integraciones que consultan la API de registro de auditoría deben consultar con una frecuencia máxima de 1750 consultas por hora. Además, si la integración recibe un error de límite de velocidad (normalmente una respuesta 403 o 429), debe esperar antes de realizar otra solicitud a la API. Consulta Límites de volumen de la API de REST y Procedimientos recomendados para usar la API de REST.

Ejemplo 1: Todos los eventos de una empresa, para una fecha específica, con paginación

Puedes usar paginación basada en cursor. Para obtener más información sobre la paginación, consulta Uso de la paginación en la API de REST.

La consulta siguiente busca eventos de registro de auditoría creados el 1 de enero de 2022 en la empresa avocado-corp y devuelve la primera página con un máximo de 100 elementos por página mediante paginación. Para obtener más información sobre la paginación, consulta Uso de la paginación en la API de REST. La marca --include hace que se devuelvan los encabezados junto con la respuesta.

curl --include -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&per_page=100"

Si hay más de 100 resultados, el encabezado link incluirá direcciones URL para capturar las páginas siguientes, primera y anteriores de los resultados.

link: <https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42NjQzODMzNTk5MjdlKzEyfDloQzBxdURzaFdVbVlLWjkxRU9mNXc%3D&before=>; rel="next",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=>; rel="first",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=MS42Njc4NDA2MjM4MzNlKzEyfExqeG5sUElvNEZMbG1XZHA5akdKTVE%3D>; rel="prev"

Copia el vínculo de paginación correspondiente en la siguiente solicitud. Por ejemplo:

curl -I -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42Njc4NDA2MjM5NDFlKzEyfHRYa3AwSkxUd2xyRjA5bWxfOS1RbFE%3D&before="

Ejemplo 2: Eventos para solicitudes de incorporación de cambios en una empresa, para una fecha y un actor específicos

Puede especificar varias frases de búsqueda, como created y actor, si las separa en la dirección URL formada con el símbolo + o el código de caracteres ASCII %20.

La consulta siguiente busca eventos de registro de auditoría para las solicitudes de incorporación de cambios, donde el evento se ha producido el 1 de enero de 2022 o después en la empresa avocado-corp y la acción la ha realizado el usuario octocat:

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=action:pull_request+created:>=2022-01-01+actor:octocat"

Ejemplo 3: Eventos para la actividad de Git en una empresa, para una fecha y un actor específicos

Puedes buscar eventos de Git en una empresa, como la clonación, la captura y la inserción, agregando include=git como parámetro en la dirección URL. Como alternativa, puedes usar include=all para buscar eventos web y eventos de Git.

La consulta siguiente busca eventos de registro de auditoría para la actividad de Git, donde el evento se ha producido después del 1 de enero de 2024 en la empresa avocado-corp y la acción la ha realizado el usuario octocat.

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:>=2024-01-01+actor:octocat&include=git"