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

Artigo
10/07/2024

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 oferece suporte à autenticação com credenciais de aplicativo autônomo e de 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 o espaço de trabalho Clientes, 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. A ID da Microsoft é igual à ID do cliente (customer-tenant-id).
Um identificador de assinatura.

Essa API retorna o consumo diário e horário não classificado por um período de tempo arbitrário. No entanto, essa API não tem suporte para planos do Azure. Se você tiver um plano do Azure, consulte os artigos Obter itens de linha de consumo não faturados e Obter itens de linha de consumo faturados por fatura. Estes artigos descrevem como obter o consumo avaliado em um nível diário por metro por recurso. Esse consumo de taxa é equivalente aos dados de grãos diários 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 períodos atuais e anteriores para obter estimativas de uso não faturadas. Dados de grãos por hora e filtros de intervalo de datas arbitrários não têm suporte no momento 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 cobrança. Você não deve esperar que os resultados do resumo do arquivo de reconciliação correspondam ao resultado recuperado dessa API exatamente pelo 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 cobrança é encerrado, todo o uso até o final do dia em que o período de cobrança termina é incluído no arquivo de reconciliação. Qualquer uso atrasado dentro do período de faturamento 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 de resposta for maior do 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 Legada 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 de 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 eles são Administradores 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 de Assinatura do Commerce.

C#

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

Obtenha o ID do cliente e o 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. Esta etapa é necessária, porque 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 SDK Java do Partner Center pode ser usado para gerenciar recursos do Partner Center. É um projeto de código aberto mantido pela comunidade de parceiros e não é oficialmente suportado pela 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. Depois, você chama 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 PowerShell do Partner Center pode ser usado para gerenciar recursos do Partner Center. É um projeto de código aberto mantido pela comunidade de parceiros e não é oficialmente suportado pela 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 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 da solicitação
GET	{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 do URI

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

Nome	Digitar	Obrigatória	Descrição
id de locatário do cliente	string	Sim	Uma cadeia com formato de GUID que identifica o cliente.
id da assinatura	string	Sim	Uma cadeia com formato de GUID que identifica a assinatura.
start_time	string no formato de deslocamento de data-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-hora UTC	Sim	O final do intervalo de tempo que representa quando a utilização foi relatada no sistema de faturamento.
granularidade	string	Não	Define a granularidade das agregações de uso. As opções disponíveis são: `daily` (padrão) e `hourly`.
show_details	boolean	Não	Especifica se deve obter os detalhes de uso no nível da instância. O padrão é `true`.
tamanho	número	Não	Especifica o número de agregações retornadas por uma única chamada de API. O padrão é 1000. O máximo é 1000.

Cabeçalhos da solicitação

Para obter mais informações, confira 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 7/2 - 8/1. Esses resultados podem não corresponder exatamente (consulte a seção API de utilização do Azure para obter detalhes).

Esta solicitação de exemplo retorna dados de utilização relatados no sistema de cobrança entre 7/2 às 12h (UTC) e 8/2 à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 êxito e de erro 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 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"
      }
    }
  ]
}

Compartilhar via