Skip to main content

Como usar a API do log de auditoria para sua empresa

Saiba como recuperar eventos corporativos programaticamente com a API REST.

Quem pode usar esse recurso?

Enterprise owners and site administrators

Note

Webhooks podem ser uma boa alternativa ao log de auditoria ou à pesquisa de API para determinados casos de uso. Os webhooks são uma maneira de o GitHub notificar seu servidor quando houver eventos específicos para um repositório, organização ou empresa. Em comparação com a API ou com a pesquisa de log de auditoria, os webhooks podem ser mais eficientes se você quiser apenas conhecer e, possivelmente, registrar quando determinados eventos ocorrerem em sua empresa, organização ou repositório. Confira "Documentação de webhooks".

Mantenha a conformidade e proteja a propriedade intelectual com pontos de extremidade relacionados ao log de auditoria. Confira "Pontos de extremidade da API REST para logs de auditoria corporativa" e "Pontos de extremidade de API REST para organizações".

Para obter mais informações sobre os eventos específicos que você pode acessar por meio dos pontos de extremidade do log de auditoria, consulte os artigos a seguir.

Detalhes do log de auditoria

O log de auditoria lista os eventos disparados por atividades que afetam sua empresa. Os logs de auditoria de GitHub Enterprise Server são retidos indefinidamente, a menos que um proprietário da empresa configure um período de retenção diferente. Consulte "Configurando o log de auditoria da sua empresa."

Por padrão, são exibidos apenas os eventos dos últimos três meses. Para ver eventos mais antigos, você deve especificar um intervalo de datas com o parâmetro created. Confira "Noções básicas de sintaxe de pesquisa".

Os carimbos de data e hora e os campos de data na resposta da API são medidos em milissegundos de época UTC.

É possível usar o escopo read:audit_log para acessar o log de auditoria por meio da API.

Exemplo 1: todos os eventos em uma empresa, para uma data específica, com paginação

Você pode usar a paginação baseada em página. Para saber mais sobre paginação, confira "Como usar paginação na API REST".

A consulta abaixo procura eventos de log de auditoria criados em 1º de janeiro de 2022 na empresa avocado-corp e retorna a primeira página com no máximo 100 itens por página usando paginação. Para saber mais sobre paginação, confira "Como usar paginação na API REST".

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"http(s)://HOSTNAME/api/v3/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&page=1&per_page=100"

Exemplo 2: eventos para solicitações de pull em uma empresa, para uma data e um ator específicos

Você pode especificar várias frases de pesquisa, como created e actor, separando-as na URL formada com o símbolo + ou o código de caractere ASCII %20.

A consulta abaixo pesquisa eventos de log de auditoria para solicitações de pull, em que o evento ocorreu em 1º de janeiro de 2022 ou após essa data na empresa avocado-corp e em que a ação foi executada pelo usuário octocat:

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"http(s)://HOSTNAME/api/v3/enterprises/avocado-corp/audit-log?phrase=action:pull_request+created:>=2022-01-01+actor:octocat"

Exemplo 3: eventos para atividade do Git em uma empresa, para uma data e ator específicos

Você pode pesquisar eventos do Git em uma empresa, como clonagem, pesquisa e envio, adicionando include=git como parâmetro na URL. Como alternativa, você pode usar include=all para pesquisar eventos da Web e eventos do Git.

A consulta abaixo procura eventos de log de auditoria para atividades do Git, em que o evento ocorreu após 1º de janeiro de 2024, na empresa avocado-corp, e a ação foi executada pelo usuário octocat.

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"http(s)://HOSTNAME/api/v3/enterprises/avocado-corp/audit-log?phrase=created:>=2024-01-01+actor:octocat&include=git"