Automatizando relatórios de uso com a API REST

Depois de fazer a transição para a cobrança limitada, convém controlar automaticamente o uso e os custos dos recursos pagos GitHub em seus sistemas de relatórios internos. Por exemplo, talvez você queira monitorar gastos ao longo do tempo, reconciliar faturas ou alimentar dados de uso em ferramentas financeiras ou de BI.

Neste tutorial, você aprenderá a usar a API REST para recuperar dados de uso de cobrança, filtre-os por período de tempo ou centro de custo e automatize relatórios recorrentes no nível do usuário, da organização ou da empresa. Você também aprenderá a interpretar campos-chave na resposta para que possa transformar dados brutos de uso em insights de custo significativos.

Pré-requisitos

Antes de começar este tutorial, verifique se:

Você tem acesso aos dados de cobrança no nível em que deseja relatar:
- Relatórios no nível do usuário: titular da conta
- Relatórios no nível da organização: proprietário da organização ou gerente de cobrança
- Relatórios de nível empresarial: administrador corporativo ou gerente de cobrança
Você está familiarizado com a criação de solicitações autenticadas para a API REST. Para obter uma introdução, confira Usando a API REST.
Você se autentica usando um personal access token (classic). Os endpoints de uso para cobrança não dão suporte a fine-grained personal access tokens.

Dependendo das suas necessidades de relatório, talvez você também queira acessar um sistema interno (como uma planilha, um banco de dados ou uma ferramenta de BI), em que você pode armazenar e analisar os dados de uso recuperados da API.

Etapa 1: Decidir em qual nível relatar

Decida em qual nível de conta você deseja relatar. Isso determina qual endpoint da API REST você chamará e o que o seu relatório incluirá.

Escolha o nível de relatório que melhor corresponda à sua meta:

Nível de relatório	Quando usar isso

          **User** | Você deseja um relatório para uma única conta, por exemplo, para entender o uso pessoal e os custos. |

| Organização | Você deseja controlar o uso e os custos de uma organização específica, por exemplo, para monitoramento no nível da equipe ou reembolso. | | Empresa | Você deseja uma exibição centralizada em várias organizações, por exemplo, relatórios financeiros ou relatórios do centro de custos. |

Depois de escolher um nível de relatório, você usará o ponto de extremidade correspondente na próxima etapa para recuperar dados de uso e criar um relatório automatizado.

Etapa 2: recuperar dados de uso para produtos pagos

Depois de decidir em qual nível relatar, use a API REST para recuperar dados de uso para produtos pagos GitHub . Para todos os pontos de extremidade, consulte Uso de faturamento.

GitHub fornece dois tipos de dados de uso de cobrança:

        **Resumos de uso** – dados de uso agregado e custo para todos os produtos pagos.

        **Uso de solicitação Premium** – dados detalhados de uso e cobrança para solicitações premium, incluindo cotas e uso excessivo.

Na maioria dos cenários de relatório, você começará com um resumo de uso para entender o uso e os gastos gerais e, em seguida, usará dados de uso de solicitação premium quando precisar de informações mais profundas sobre o consumo de solicitações premium.

Recuperar um resumo de uso

Use o endpoint de resumo do uso que corresponde ao nível de relatório escolhido na Etapa 1.

Por exemplo, para recuperar um resumo de uso de uma empresa, faça uma solicitação para:

/enterprises/{enterprise}/settings/billing/usage/summary

Você deve autenticar sua solicitação para este endpoint.

          **Exemplo usando curl**

curl -L \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/usage/summary

Substitua ENTERPRISE pelo slug da empresa e defina a variável de ambiente GITHUB_TOKEN como personal access token para as permissões de cobrança necessárias.

          **Exemplo usando o GitHub CLI**

gh api \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /enterprises/ENTERPRISE/settings/billing/usage/summary

Esse endpoint retorna por padrão dados de uso agregados para todos os produtos pagos para o ano atual. Cada entrada inclui informações como o produto, o tipo de unidade, a quantidade usada e o valor cobrado.

Você pode usar a mesma abordagem para recuperar resumos de uso para uma organização ou usuário chamando o endpoint equivalente para esse nível de conta específica.

Recuperar o uso de solicitação premium

Se você precisar relatar especificamente sobre o consumo de solicitação premium, use o premium_request/usage endpoint para o mesmo nível de conta. Este endpoint fornece detalhes adicionais, como o uso incluído, excedentes cobrados e a cota restante.

Na próxima etapa, você aprenderá a filtrar dados de uso por período de tempo ou centro de custo para gerar relatórios mais direcionados.

Etapa 3: Filtrar dados de uso por período de tempo ou centro de custo

Por padrão, os endpoints de resumo de utilização retornam dados para o ano atual. Para gerar relatórios mais direcionados ou analisar tendências ao longo do tempo, você pode filtrar dados de uso usando parâmetros de consulta.

Filtrar por período de tempo

Você pode limitar os dados de uso retornados especificando um ou mais dos seguintes parâmetros de consulta:

year
month
day
hour

Por exemplo, para recuperar dados de uso de um mês específico, inclua os parâmetros year e month na solicitação.

GET /enterprises/{enterprise}/settings/billing/usage/summary?year=2024&month=12

A filtragem por período de tempo é útil quando você deseja:

Gerar relatórios de uso mensal ou diário
Comparar o uso antes e depois de uma alteração, como habilitar um novo recurso
Conciliar o consumo com as faturas para um período de cobrança específico

Filtrar por centro de custo (somente para grandes empresas)

Se você estiver recuperando dados de uso de nível empresarial, também poderá filtrar os resultados por centro de custo usando o cost_center_id parâmetro de consulta.

A filtragem por centro de custo permite que você:

Atribuir uso e custos a equipes ou unidades de negócios específicas
Gerar relatórios específicos para os centros de custos destinados a responsáveis de finanças ou de liderança

A filtragem dos centros de custo está disponível apenas para endpoints de resumo de uso para empresas.

Na próxima etapa, você aprenderá a automatizar essas chamadas à API para gerar relatórios de uso recorrentes.

Etapa 4: Automatizar relatórios de uso recorrentes

Depois de identificar os dados de uso que deseja coletar e como filtrá-los, você pode automatizar seus relatórios executando as mesmas solicitações de API em um agendamento recorrente.

Os padrões comuns de automação incluem:

Executando solicitações de API agendadas (por exemplo, diárias ou mensais) para coletar dados de uso
Armazenando os resultados em um sistema interno, como um banco de dados, uma planilha ou uma ferramenta de BI
Usando os dados para monitorar tendências, detectar alterações no uso ou dar suporte a revisões de custos

Ao automatizar relatórios, a consistência é importante. Use o mesmo nível de relatório, filtros e intervalos de tempo cada vez para que as tendências de uso sejam comparáveis ao longo do tempo.

Por exemplo, é possível:

Executar um resumo mensal de uso de nível empresarial para controlar os gastos gerais
Gerar relatórios específicos do centro de custos para o rateio ou demonstração de custos internos.
Monitorar o crescimento do uso após habilitar novos recursos pagos

Na próxima etapa, você aprenderá a interpretar os campos de uso e custo retornados pela API para que você possa transformar dados brutos em insights significativos.

Etapa 5: Interpretar campos de uso e custo na resposta à API

A resposta de resumo de uso inclui informações de uso e custo . Entender como esses campos se relacionam entre si ajuda você a interpretar gastos, uso incluído e excedentes cobrados.

Cada item de uso inclui:

Uma quantidade, que representa a quantidade de uso para um produto e um tipo de unidade específicos
Um netAmount, que representa o custo cobrado para esse uso
Um discountAmount, que representa o uso coberto por cotas ou descontos incluídos

Em geral:

Usar quantidade para entender quanto de um produto foi consumido
Usar netAmount para entender o que foi cobrado
Usar discountAmount para entender quanto uso foi incluído ou descontado

Por exemplo, uma quantidade alta com um valor líquido baixo pode indicar que a maior parte do uso foi coberta por cotas incluídas, enquanto um aumento do valor líquido ao longo do tempo pode indicar maior uso pago.

Diferentes produtos relatam o uso usando diferentes tipos de unidade (como minutos, gigabytes ou solicitações). Para calcular métricas específicas do produto ou reproduzir valores da plataforma de cobrança anterior, talvez seja necessário filtrar itens de uso por tipo de produto e unidade e agregar os resultados. Exemplos detalhados estão disponíveis na documentação de referência vinculada na próxima etapa.

Etapa 6: Calcular métricas de uso específicas do produto

Em alguns casos, talvez seja necessário calcular as métricas de uso específicas do produto da resposta de resumo de uso. Isso é mais relevante se você quiser gerar relatórios personalizados para um produto específico ou reproduzir valores usados em relatórios herdados.

Para calcular essas métricas, você normalmente filtra itens de uso por product e unitType, em seguida, agrega campos como quantity, netAmounte discountAmount.

Para obter exemplos detalhados e cálculos específicos do produto, consulte Introdução à cobrança e ao licenciamento.