Verwenden der Überwachungsprotokoll-API
Du kannst mit dem Überwachungsprotokoll mithilfe der GraphQL-API oder der REST-API interagieren.
Zeitstempel und Datumsfelder in der API-Antwort werden in UTC-Epochenmillisekunden gemessen.
Abfragen der GraphQL-API des Überwachungsprotokolls
Zur Sicherstellung, dass dein geistiges Eigentum sicher ist und du die Compliance für dein Unternehmen aufrechterhältst, kannst du die GraphQL-API des Überwachungsprotokolls verwenden, um Kopien deiner Überwachungsprotokolldaten aufzubewahren und zu überwachen: * Zugriff auf Ihre Organisations- oder Repositoryeinstellungen
- Änderungen an Berechtigungen
- Hinzugefügte oder entfernte Benutzer*innen in einer Organisation, einem Repository oder einem Team
- Benutzerinnen, die zu Administratorinnen ernannt werden
- Änderungen an Berechtigungen einer GitHub App
Beachte, dass du Git-Ereignisse nicht mithilfe der Überwachungsprotokoll-API abrufen kannst.
Die GraphQL-Antwort kann Daten für bis zu 90 bis 120 Tage beinhalten.
Beispiel 1: Mitglieder, die in einem Unternehmen Organisationen hinzugefügt oder daraus entfernt wurden
Die folgende Abfrage ruft die Überwachungsprotokolle für das Unternehmen avocado-corp ab und gibt die ersten 10 Organisationen im Unternehmen zurück, in denen die einzigen ausgeführten Aktionen darin bestanden, ein Mitglied einer Organisation hinzuzufügen oder daraus zu entfernen. Die ersten 20 Überwachungsprotokolleinträge für jede Organisation werden zurückgegeben.
Diese Abfrage verwendet das Feld auditlog (Überwachungsprotokoll) aus dem Objekt „Organization“ sowie die Objekte OrgAddMemberAuditEntry und OrgRemoveMemberAuditEntry. Das GitHub-Konto, von dem das Überwachungsprotokoll für das Unternehmen abgefragt wird, muss ein Organisationsbesitzer für jede Organisation innerhalb des Unternehmens sein.
{
enterprise(slug: "avocado-corp") {
organizations(first: 10, orderBy: {field: LOGIN, direction: DESC}) {
nodes {
name
auditLog(first: 20) {
edges {
node {
... on OrgAddMemberAuditEntry {
action
actorLogin
createdAt
}
... on OrgRemoveMemberAuditEntry {
action
actorLogin
createdAt
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}Die GraphQL-API gibt maximal 100 Knoten pro Abfrage zurück. Zum Abrufen zusätzlicher Ergebnisse musst du die Paginierung implementieren. Weitere Informationen findest du in der GraphQL-API-Dokumentation unter Ressourcenbeschränkungen und in der offiziellen GraphQL-Dokumentation unter Paginierung.
Beispiel 2: Ereignisse in einer Organisation, für ein bestimmtes Datum und einen bestimmten Akteur
Du kannst mehrere Suchbegriffe wie z. B. created und actor angeben, indem du sie in deiner Abfragezeichenfolge durch ein Leerzeichen trennst.
Die folgende Abfrage ruft alle Überwachungsprotokolle für das Unternehmen avocado-corp ab, die sich auf die Organisation octo-org beziehen und bei denen die Aktionen vom Benutzer octocat am oder nach dem 1. Januar 2022 ausgeführt wurden. Die ersten 20 Überwachungsprotokolleinträge werden zurückgegeben, wobei der neueste Protokolleintrag zuerst angezeigt wird.
Diese Abfrage verwendet die Schnittstelle AuditEntry. Das Konto GitHub, von dem das Überwachungsprotokoll für das Unternehmen abgefragt wird, muss ein Besitzer der Organisation octo-org sein.
{
enterprise(slug: "avocado-corp") {
organizations(first: 1, query: "octo-org") {
nodes {
name
auditLog(first: 20, query: "actor:octocat created:>=2022-01-01T00:00:00.000Z", orderBy: {field: CREATED_AT, direction: DESC}) {
edges {
node {
... on AuditEntry {
action
actorLogin
createdAt
user {
name
}
}
}
}
}
}
}
}
}Weitere Abfragebeispiele findest du im Repository für Plattformbeispiele.
Abfragen der REST-API des Überwachungsprotokolls
Zur Sicherstellung, dass dein geistiges Eigentum sicher ist und du die Compliance für dein Unternehmen aufrechterhältst, kannst du die REST-API des Überwachungsprotokolls verwenden, um Kopien deiner Überwachungsprotokolldaten aufzubewahren und zu überwachen: * Zugriff auf Ihre Organisations- oder Repositoryeinstellungen
- Änderungen an Berechtigungen
- Hinzugefügte oder entfernte Benutzer*innen in einer Organisation, einem Repository oder einem Team
- Benutzerinnen, die zu Administratorinnen ernannt werden
- Änderungen an Berechtigungen einer GitHub App
Im Überwachungsprotokoll werden Ereignisse aufgelistet, die durch Aktivitäten ausgelöst werden, die sich auf dein Unternehmen auswirken. Überwachungsprotokolle für GitHub Enterprise Server werden unbegrenzt beibehalten, es sei denn, eine Unternehmensbesitzerin hat einen anderen Aufbewahrungszeitraum konfiguriert. Weitere Informationen findest du unter Konfigurieren des Überwachungsprotokolls für dein Unternehmen.
Standardmäßig werden nur Ereignisse aus den letzten drei Monaten angezeigt. Um ältere Ereignisse anzuzeigen, musst du einen Datumsbereich mit dem created-Parameter angeben. Weitere Informationen findest du unter Grundlagen der Suchsyntax.
Weitere Informationen zur REST-API des Überwachungsprotokolls findest du unter Unternehmensverwaltung und Organisationen.
Beispiel 1: Alle Ereignisse in einem Unternehmen, für ein bestimmtes Datum, mit Paginierung
Du kannst die seitenbasierte oder cursorbasierte Paginierung verwenden. Weitere Informationen zur Paginierung findest du unter Verwenden der Paginierung in der REST-API.
Beispiel mit seitenbasierter Paginierung
Die folgende Abfrage sucht nach Überwachungsprotokollereignissen, die am 1. Januar 2022 im Unternehmen avocado-corp erstellt wurden, und gibt die erste Seite mit maximal 100 Elementen pro Seite mithilfe der Paginierung zurück. Weitere Informationen zur Paginierung findest du unter Verwenden der Paginierung in der REST-API.
curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&page=1&per_page=100"Beispiel mit cursorbasierter Paginierung
Die folgende Abfrage sucht nach Überwachungsprotokollereignissen, die am 1. Januar 2022 im Unternehmen avocado-corp erstellt wurden, und gibt die erste Seite mit maximal 100 Elementen pro Seite mithilfe der Paginierung zurück. Weitere Informationen zur Paginierung findest du unter Verwenden der Paginierung in der REST-API. Das Flag --include bewirkt, dass die Header zusammen mit der Antwort zurückgegeben werden.
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"
Wenn mehr als 100 Ergebnisse vorhanden sind, enthält der link-Header URLs zum Abrufen der nächsten, ersten und vorherigen Ergebnisseiten.
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"
Kopiere den entsprechenden Paginierungslink in deine nächste Anforderung. Beispiel:
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="Beispiel 2: Ereignisse bei Pullanforderungen in einem Unternehmen, für ein bestimmtes Datum und einen bestimmten Akteur
Du kannst mehrere Suchbegriffe wie z. B. created und actor angeben, indem du sie in deiner formatierten URL mit dem Symbol + oder dem ASCII-Zeichencode %20 trennst.
Die folgende Abfrage sucht nach Überwachungsprotokollereignissen für Pullanforderungen, bei denen das Ereignis am oder nach dem 1. Januar 2022 im avocado-corp Unternehmen eingetreten ist und die Aktion vom Benutzer octocat ausgeführt wurde:
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"