Obter registros de utilização de um cliente para o Azure

2025-05-11

Aplica-se a: Partner Center | Partner Center para o Microsoft Cloud for US Government

Você pode obter os registros de utilização da assinatura do Azure de um cliente por um período especificado por meio da API de utilização do Azure.

Pré-requisitos

Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário dá suporte à autenticação com credenciais de aplicativo autônomo e Aplicativo+Usuário.
Uma ID do cliente (customer-tenant-id). Se você não souber a ID do cliente, poderá procurá-la no Partner Center selecionando a área de trabalho Clientes, depois o cliente na lista de clientes e, em seguida, Conta. Na página Conta do cliente, procure a ID da Microsoft na seção Informações da Conta do Cliente. O ID da Microsoft é o mesmo que o ID do cliente (customer-tenant-id).
Um identificador de assinatura.

Essa API retorna o consumo diário e por hora não classificado por um período de tempo arbitrário. No entanto, não há suporte para essa API nos planos do Azure. Se você tiver um plano do Azure, consulte os artigos Obter itens de linha de consumo não cobrados por fatura e Obter itens de linha de consumo cobrados por fatura . Esses artigos descrevem como obter o consumo nominal em um nível diário por metro por recurso. Esse consumo de taxa é equivalente aos dados de granularidade diária fornecidos pela API de utilização do Azure. Você precisará usar o identificador de fatura para recuperar dados de uso faturados. Ou você pode usar os períodos atual e anterior para obter estimativas de uso não cobradas. No momento, não há suporte para dados de granulação por hora e filtros de intervalo de datas arbitrários para recursos de assinatura do plano do Azure.

API de utilização do Azure

Essa API de utilização do Azure fornece acesso a registros de utilização por um período de tempo que representa quando a utilização foi relatada no sistema de cobrança. Ele fornece acesso aos mesmos dados de utilização usados para criar e calcular o arquivo de reconciliação. No entanto, ele não tem conhecimento da lógica do arquivo de reconciliação do sistema de faturamento. Você não deve esperar que os resultados do resumo do arquivo de reconciliação correspondam ao resultado recuperado dessa API exatamente para o mesmo período de tempo.

Por exemplo, o sistema de faturamento usa os mesmos dados de utilização e aplica regras de atraso para determinar o que é contabilizado em um arquivo de reconciliação. Quando um período de faturamento é fechado, todo o uso até o final do dia em que o período de faturamento termina é incluído no arquivo de reconciliação. Qualquer uso atrasado dentro do período de cobrança relatado dentro de 24 horas após o término do período de cobrança é contabilizado no próximo arquivo de reconciliação. Para obter as regras de atraso de como o parceiro é cobrado, consulte Obter dados de consumo para uma assinatura do Azure.

Essa API REST é paginada. Se a carga útil da resposta for maior que uma única página, você deverá seguir o próximo link para obter a próxima página de registros de utilização.

Cenário: o Parceiro A transferiu a propriedade de cobrança da Assinatura Herdada do Azure (145P) para o Parceiro B

Se um parceiro transferir a propriedade de cobrança de uma assinatura herdada do Azure para outro parceiro, quando novo, o novo parceiro chamar a API de Utilização para assinatura transferida, ele precisará usar a ID da Assinatura do Commerce (que aparece em sua conta do Partner Center) em vez da ID de Direito do Azure. A ID de Direito do Azure aparece para o Parceiro B somente quando ele é Administrador em nome de (AOBO) para o portal do Azure do Cliente.

Para chamar com êxito a API de Utilização para a assinatura transferida, o novo parceiro precisa usar a ID da Assinatura do Commerce.

C#

Para obter os Registros de Utilização do Azure:

Obtenha a ID do cliente e a ID da assinatura.
Chame o método IAzureUtilizationCollection.Query para retornar um ResourceCollection que contém os registros de utilização.
Obtenha um enumerador de registro de utilização do Azure para percorrer as páginas de utilização. Essa etapa é necessária, pois a coleção de recursos é paginada.

Exemplo: aplicativo de teste de console
Projeto: Exemplos de SDK do Partner Center
Classe: GetAzureSubscriptionUtilization.cs

// IAggregatePartner partnerOperations;
// string customerId;
// string subscriptionId;

IPartner partner = PartnerService.Instance.CreatePartnerOperations(credentials);

// Retrieve the utilization records for the last year in pages of 100 records.
var utilizationRecords = partner.Customers[customerId].Subscriptions[subscriptionId].Utilization.Azure.Query(
    DateTimeOffset.Now.AddYears(-1),
    DateTimeOffset.Now,
    size: 100);

// Create an Azure utilization enumerator which will aid us in traversing the utilization pages.
var utilizationRecordEnumerator = partner.Enumerators.Utilization.Azure.Create(utilizationRecords);

while (utilizationRecordEnumerator.HasValue)
{
    //
    // Insert code here to work with this page.
    //

    // Get the next page.
    utilizationRecordEnumerator.Next();
}

Java

O Partner Center Java SDK pode ser usado para gerenciar os recursos do Partner Center. É um projeto de software livre mantido pela comunidade de parceiros e não tem suporte oficial da Microsoft. Caso se depare com um problema, você pode obter ajuda da comunidade ou abrir um problema no GitHub.

Para obter os Registros de Utilização do Azure, primeiro você precisa de um identificador de cliente e um identificador de assinatura. Em seguida, chame a função IAzureUtilizationCollection.query para retornar um ResourceCollection que contém os registros de utilização. Como a coleção de recursos é paginada, você deve obter um enumerador de registro de utilização do Azure para percorrer as páginas de utilização.

// IAggregatePartner partnerOperations;
// String customerId;
// String subscriptionId;

ResourceCollection<AzureUtilizationRecord> utilizationRecords = partnerOperations.getCustomers()
  .byId(customerId).getSubscriptions().byId(subscriptionId)
  .getUtilization().getAzure().query(
      new DateTime().minusYears(1),
      new DateTime(),
      AzureUtilizationGranularity.Daily,
      true,
      100);

// Create an Azure utilization enumerator which will aid us in traversing the utilization pages
IResourceCollectionEnumerator<ResourceCollection<AzureUtilizationRecord>> utilizationRecordEnumerator =
    partnerOperations.getEnumerators().getUtilization().getAzure().create(utilizationRecords);

while (utilizationRecordEnumerator.hasValue())
{
    //
    // Insert code here to work with this page.
    //

    // get the next page
    utilizationRecordEnumerator.next();
}

PowerShell

O módulo do PowerShell do Partner Center pode ser usado para gerenciar recursos do Partner Center. É um projeto de software livre mantido pela comunidade de parceiros e não tem suporte oficial da Microsoft. Caso se depare com um problema, você pode obter ajuda da comunidade ou abrir um problema no GitHub.

Para obter os Registros de Utilização do Azure, primeiro você precisa de um identificador de cliente e um identificador de assinatura. Em seguida, chame o Get-PartnerCustomerSubscriptionUtilization. Esse comando retornará todos os registros disponíveis para o período de tempo especificado.

# $customerId
# $subscriptionId

Get-PartnerCustomerSubscriptionUtilization -CustomerId $customerId -SubscriptionId $subscriptionId -StartDate (Get-Date).AddDays(-2).ToUniversalTime() -Granularity Hourly -ShowDetails

Solicitação REST

Sintaxe da solicitação

Método	URI de solicitação
OBTER	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id}/utilizations/azure?start_time={start-time}&end_time={end-time}&granularity={granularity}&show_details={True}

Parâmetros de URI

Use os parâmetros de caminho e consulta a seguir para obter os registros de utilização.

Nome	Tipo	Obrigatório	Descrição
ID do locatário do cliente	corda	Sim	Uma cadeia de caracteres formatada em GUID que identifica o cliente.
id da assinatura	corda	Sim	Uma cadeia de caracteres formatada por GUID que identifica a assinatura.
hora de início	string no formato de deslocamento de data e hora UTC	Sim	O início do intervalo de tempo que representa quando a utilização foi relatada no sistema de faturamento.
end_time	string no formato de deslocamento de data e hora UTC	Sim	O fim do intervalo de tempo que representa quando a utilização foi relatada no sistema de faturamento.
granularidade	corda	Não	Define a granularidade das agregações de uso. As opções disponíveis são: `daily` (padrão) e `hourly`.
show_details	booleano	Não	Especifica se os detalhes de uso no nível da instância devem ser obtidos. O padrão é `true`.
tamanho	número	Não	Especifica o número de agregações retornadas por uma única chamada à API. O padrão é 1000. O máximo é 1000.

Cabeçalhos da solicitação

Para mais informações, consulte os cabeçalhos REST do Partner Center.

Corpo da solicitação

Nenhum

Exemplo de solicitação

A solicitação de exemplo a seguir produz resultados semelhantes aos que o arquivo de reconciliação mostrará para o período de 02/07 a 01/08. Esses resultados podem não corresponder exatamente (consulte a seção API de utilização do Azure para obter detalhes).

Este exemplo de solicitação retorna dados de utilização relatados no sistema de faturamento entre 02/07 às 12h (UTC) e 02/08 às 12h (UTC).

GET https://api.partnercenter.microsoft.com/v1/customers/E499C962-9218-4DBA-8B83-8ADC94F47B9F/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/utilizations/azure?start_time=2017-07-02T00:00:00-08:00&end_time=2017-08-02T00:00:00-08:00 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: e6a3b6b2-230a-4813-999d-57f883b60d38
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US
Host: api.partnercenter.microsoft.com

Resposta REST

Se for bem-sucedido, esse método retornará uma coleção de recursos do Registro de Utilização do Azure no corpo da resposta. Se os dados de utilização do Azure ainda não estiverem prontos em um sistema dependente, esse método retornará um Código de Status HTTP 204 com um cabeçalho Retry-After.

Códigos de erro e êxito de resposta

Cada resposta vem com um código de status HTTP que indica êxito ou falha e informações de depuração adicionais. Use uma ferramenta de rastreamento de rede para ler o código de status HTTP, o tipo de código de erro e os parâmetros adicionais.

Exemplo de resposta

HTTP/1.1 200 OK
Content-Length: 2630
Content-Type: application/json; charset=utf-8
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: e6a3b6b2-230a-4813-999d-57f883b60d38
MS-CV: PjuGoYrw806o6A3Y.0
MS-ServerId: 030020525
Date: Fri, 04 Aug 2017 23:48:28 GMT

{
  "totalCount": 2,
  "items": [
    {
      "usageStartTime": "2017-06-07T17:00:00-07:00",
      "usageEndTime": "2017-06-08T17:00:00-07:00",
      "resource": {
        "id": "8767aeb3-6909-4db2-9927-3f51e9a9085e",
        "name": "Storage Admin",
        "category": "Storage",
        "subcategory": "Block Blob",
        "region": "Azure Stack"
      },
      "quantity": 0.217790327034891,
      "unit": "1 GB/Hr",
      "infoFields": {},
      "instanceData": {
        "resourceUri": "/subscriptions/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/resourcegroups/system.local/providers/Microsoft.Storage/storageaccounts/srphealthaccount",
        "location": "azurestack",
        "partNumber": "",
        "orderNumber": "",
        "additionalInfo": {
          "azureStack.MeterId": "09F8879E-87E9-4305-A572-4B7BE209F857",
          "azureStack.SubscriptionId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
          "azureStack.Location": "local",
          "azureStack.EventDateTime": "06/05/2017 06:00:00"
        }
      },
      "attributes": {
        "objectType": "AzureUtilizationRecord"
      }
    },
    {
      "usageStartTime": "2017-06-07T17:00:00-07:00",
      "usageEndTime": "2017-06-08T17:00:00-07:00",
      "resource": {
        "id": "8767aeb3-6909-4db2-9927-3f51e9a9085e",
        "name": "Storage Admin",
        "category": "Storage",
        "subcategory": "Block Blob",
        "region": "Azure Stack"
      },
      "quantity": 0.217790327034891,
      "unit": "1 GB/Hr",
      "infoFields": {},
      "instanceData": {
        "resourceUri": "/subscriptions/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/resourcegroups/system.local/providers/Microsoft.Storage/storageaccounts/srphealthaccount",
        "location": "azurestack",
        "partNumber": "",
        "orderNumber": "",
        "additionalInfo": {
          "azureStack.MeterId": "09F8879E-87E9-4305-A572-4B7BE209F857",
          "azureStack.SubscriptionId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
          "azureStack.Location": "local",
          "azureStack.EventDateTime": "06/05/2017 06:00:00"
        },
        "attributes": {
          "objectType": "AzureUtilizationRecord"
        }
      },

      "links": {
        "self": {
          "uri": "customers/E499C962-9218-4DBA-8B83-8ADC94F47B9F/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/utilizations/azure?start_time=2017-06-10T00:00:00Z&end_time=2017-07-09T00:00:00Z&granularity=Daily&show_details=True&size=1000",
          "method": "GET",
          "headers": []
        }
      },
      "attributes": {
        "objectType": "Collection"
      }
    }
  ]
}