Utilisation de l’API de journal d’audit pour votre entreprise

Apprenez à récupérer par programmation des événements d’entreprise avec l’API REST.

Qui peut utiliser cette fonctionnalité ?

Enterprise owners

Dans cet article

Note

Les webhooks peuvent être une bonne alternative au journal d’audit ou à l’interrogation d’API pour certains cas d'utilisation. Les webhooks sont un moyen pour GitHub de notifier votre serveur lorsque des événements spécifiques se produisent pour un référentiel, une organisation ou une entreprise. Par rapport à l’API ou à la recherche dans le journal d’audit, les webhooks peuvent être plus efficaces si vous souhaitez simplement apprendre et éventuellement journaliser quand certains événements se produisent sur votre entreprise, organisation ou référentiel. Consultez « Documentation sur les webhooks ».

Maintenez la conformité et sécurisez la propriété intellectuelle avec les points de terminaison relatifs au journal d’audit. Consultez « Points de terminaison d’API REST pour les journaux d’audit de l’entreprise » et « Points de terminaison d’API REST pour les organisations. »

Pour plus d’informations sur les événements spécifiques auxquels vous pouvez accéder via les points de terminaison de journal d’audit, consultez les articles suivants.

Détails du journal d'audit

Le journal d’audit liste les événements déclenchés par les activités qui affectent votre entreprise au cours des 180 derniers jours. Le journal d’audit conserve les événements Git pendant sept jours.

Par défaut, seuls les événements des trois derniers mois sont affichés. Pour voir les événements plus anciens, vous devez spécifier une plage de dates avec le paramètre created. Consultez « Compréhension de la syntaxe de recherche ».

Les horodatages et les champs de date de la réponse de l’API sont mesurés en millisecondes d’époque UTC.

Vous pouvez utiliser l’étendue read:audit_log pour accéder au journal d’audit via l’API.

Limite du taux

Chaque point de terminaison d’API de journal d’audit a une limite de débit de 1 750 requêtes par heure pour une combinaison donnée d’utilisateur et d’adresse IP. Pour éviter la limitation du débit, les intégrations qui interrogent l’API du journal d’audit doivent effectuer des requêtes à une fréquence maximale de 1 750 requêtes par heure. En outre, si votre intégration reçoit une erreur de limite de débit (généralement une réponse 403 ou 429), elle doit attendre avant d’effectuer une autre demande à l’API. Consultez « Limites de débit pour l'API REST » et « Meilleures pratiques pour utiliser l'API REST ».

Exemple 1 : Tous les événements d’une entreprise pour une date spécifique, avec pagination

Vous pouvez utiliser la pagination basée sur le curseur. Pour plus d’informations sur la pagination, consultez « Utilisation de la pagination dans l’API REST ».

La requête ci-dessous recherche les événements de journal d’audit créés le 1er janvier 2022 dans l’entreprise avocado-corp et retourne la première page avec un maximum de 100 éléments par page à l’aide de la pagination. Pour plus d’informations sur la pagination, consultez « Utilisation de la pagination dans l’API REST ». L’indicateur --include entraîne le retour des en-têtes avec la réponse.

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"

S’il y a plus de 100 résultats, l’en-tête link inclut des URL pour récupérer les prochaines, premières et précédentes pages des résultats.

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"

Copiez le lien de pagination correspondant dans votre prochaine requête. Par exemple :

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="

Exemple 2 : Événements pour les demandes de tirage (pull request) dans une entreprise pour une date et un acteur spécifiques

Vous pouvez spécifier plusieurs expressions de recherche, par exemple created et actor, en les séparant par le symbole + ou le code de caractère ASCII %20 dans votre URL formée.

La requête ci-dessous recherche les événements de journal d’audit pour les demandes de tirage, où l’événement s’est produit à partir du 1er janvier 2022 dans l’entreprise avocado-corp et où l’action a été effectuée par l’utilisateur 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"

Exemple 3 :Événements pour l’activité Git dans une entreprise, pour une date et un acteur spécifiques

Vous pouvez rechercher des événements Git dans une entreprise, tels que le clonage, la récupération et l’envoi (push), en ajoutant include=git en tant que paramètre dans l’URL. Vous pouvez également utiliser include=all pour rechercher à la fois des événements web et des événements Git.

La requête ci-dessous recherche les événements du journal d’audit pour l’activité Git, où l’événement s’est produit après le 1er janvier 2024 dans l’entreprise avocado-corp et où l’action a été effectuée par l’utilisateur 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"