Obter registros de utilização de um cliente para o AzureGet a customer's utilization records for Azure

Aplica-se a:Applies to:

  • Partner CenterPartner Center
  • Partner Center do Microsoft Cloud GermanyPartner Center for Microsoft Cloud Germany
  • Partner Center do Microsoft Cloud for US GovernmentPartner Center for Microsoft Cloud for US Government

Você pode obter os registros de utilização da assinatura do Azure de um cliente por um período de tempo especificado usando a API de utilização do Azure.You can get the utilization records of a customer's Azure subscription for a specified time period using the Azure utilization API.

Pré-requisitosPrerequisites

  • Credenciais, conforme descrito em Autenticação do Partner Center.Credentials as described in Partner Center authentication. Esse cenário dá suporte à autenticação com aplicativos autônomos e aplicativos + credenciais de usuário.This scenario supports authentication with both standalone app and App+User credentials.

  • Uma ID do cliente (customer-tenant-id).A customer ID (customer-tenant-id). Se você não souber a ID do cliente, poderá procurar no painel do Partner Center.If you don't know the customer's ID, you can look it up in the Partner Center dashboard. Selecione CSP no menu do Partner Center e, em seguida, Clientes.Select CSP from the Partner Center menu, followed by Customers. Selecione o cliente na lista de clientes e selecione Conta.Select the customer from the customer list, then select Account. Na página Conta do cliente, procure a ID da Microsoft na seção Informações da Conta do Cliente.On the customer’s Account page, look for the Microsoft ID in the Customer Account Info section. A ID da Microsoft é igual à ID do cliente (customer-tenant-id).The Microsoft ID is the same as the customer ID (customer-tenant-id).

  • Um identificador de assinatura.A subscription identifier.

Essa API retorna consumo não classificado diariamente e por hora por um período de tempo arbitrário.This API returns daily and hourly unrated consumption for an arbitrary time span. No entanto, essa API não tem suporte para planos do Azure.However, this API isn't supported for Azure plans. Se você tiver um plano do Azure, confira os artigos obter itens de linha de consumo não faturados e obter itens de linha de consumo cobrado da fatura em vez disso.If you have an Azure plan, see the articles Get invoice unbilled consumption line items and Get invoice billed consumption line items instead. Estes artigos descrevem como obter o consumo classificado em um nível diário por medidor por recurso.These articles describe how to get rated consumption at a daily level per meter per resource. Esse consumo de taxa é equivalente aos dados de detalhamento diários fornecidos pela API de utilização do Azure.This rate consumption is equivalent to the daily grain data provided by the Azure utilization API. Você precisará usar o identificador de fatura para recuperar dados de uso cobrados.You'll need to use the invoice identifier to retrieve billed usage data. Ou, você pode usar períodos atuais e anteriores para obter estimativas de uso não cobradas.Or, you can use current and previous periods to get unbilled usage estimates. Os dados de granulação por hora e os filtros de intervalo de datas arbitrária não têm suporte no momento para recursos de assinatura do Azure Plan.Hourly grain data and arbitrary date range filters aren't currently supported for Azure plan subscription resources.

API de utilização do AzureAzure utilization API

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.This Azure utilization API provides access to utilization records for a time period that represents when the utilization was reported in the billing system. Ele fornece acesso aos mesmos dados de utilização que são usados para criar e calcular o arquivo de reconciliação.It provides access to the same utilization data that is used to create and calculate the reconciliation file. No entanto, ele não tem conhecimento da lógica do arquivo de reconciliação do sistema de cobrança.However, it does not have knowledge of billing system reconciliation file logic. Você não deve esperar que os resultados de resumo do arquivo de reconciliação correspondam exatamente ao resultado recuperado desta API para o mesmo período de tempo.You should not expect reconciliation file summary results to match the result retrieved from this API exactly for the same time period.

Por exemplo, o sistema de cobrança usa os mesmos dados de utilização e aplica as regras de atraso para determinar o que é contabilizado em um arquivo de reconciliação.For example, the billing system takes the same utilization data and applies lateness rules to determine what is accounted for in a reconciliation file. Quando um período de cobrança é fechado, todo o uso até o final do dia em que o período de cobrança termina é incluído no arquivo de reconciliação.When a billing period closes, all usage until the end of the day that the billing period ends is included in the reconciliation file. Qualquer uso atrasado dentro do período de cobrança que é relatado dentro de 24 horas após o término do período de cobrança é considerado no próximo arquivo de reconciliação.Any late usage within the billing period that is reported within 24 hours after the billing period ends is accounted for in the next reconciliation file. Para as regras de atraso de como o parceiro é cobrado, consulte obter dados de consumo para uma assinatura do Azure.For the lateness rules of how the partner is billed, see Get consumption data for an Azure subscription.

Esta API REST é paginada.This REST API is paged. Se a carga de resposta for maior que uma única página, você deverá seguir o link seguinte para obter a próxima página de registros de utilização.If the response payload is larger than a single page, you must follow the next link to get the next page of utilization records.

C#C#

Para obter os registros de utilização do Azure:To obtain the Azure Utilization Records:

  1. Obtenha a ID do cliente e a ID da assinatura.Get the customer ID and subscription ID.

  2. Chame o método IAzureUtilizationCollection. Query para retornar uma resourcecollection que contém os registros de utilização.Call the IAzureUtilizationCollection.Query method to return a ResourceCollection that contains the utilization records.

  3. Obtenha um enumerador de registro de utilização do Azure para atravessar as páginas de utilização.Obtain an Azure utilization record enumerator to traverse the utilization pages. Esta etapa é necessária, pois a coleção de recursos é paginada.This step is required, because the resource collection is paged.

// 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();
}

JavaJava

O SDK do Java do Partner Center geralmente é usado por parceiros para gerenciar os recursos do Partner Center.The Partner Center Java SDK is commonly used by partners to manage their Partner Center resources. É um projeto de software livre mantido pela comunidade de parceiros.It's an open-source project maintained by the partner community. Esse módulo é mantido pela comunidade de parceiros e, por isso, não tem suporte oficial da Microsoft.Since this module is maintained by the partner community, it isn't officially supported by Microsoft. Caso se depare com um problema, você pode obter ajuda da comunidade ou abrir um problema no GitHub.You can get help from the community or open an issue on GitHub if you experience a problem.

Para obter os registros de utilização do Azure, primeiro você precisa de um identificador de cliente e um identificador de assinatura.To obtain the Azure Utilization Records, you first need a customer identifier and a subscription identifier. Em seguida, você chama a função IAzureUtilizationCollection. Query para retornar uma resourcecollection que contém os registros de utilização.You then call the IAzureUtilizationCollection.query function to return a ResourceCollection that contains the utilization records. 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.Because the resource collection is paged, you must then obtain an Azure utilization record enumerator to traverse the utilization pages.

// 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();
}

PowerShellPowerShell

O módulo PowerShell do Partner Center é normalmente usado por parceiros para gerenciar os recursos do Partner Center.The Partner Center PowerShell module is commonly used by partners to manage their Partner Center resources. É um projeto de software livre mantido pela comunidade de parceiros.It's an open-source project maintained by the partner community. Esse módulo é mantido pela comunidade de parceiros e, por isso, não tem suporte oficial da Microsoft.Since this module is maintained by the partner community, it isn't officially supported by Microsoft. Caso se depare com um problema, você pode obter ajuda da comunidade ou abrir um problema no GitHub.You can get help from the community or open an issue on GitHub if you experience a problem.

Para obter os registros de utilização do Azure, primeiro você precisa de um identificador de cliente e um identificador de assinatura.To obtain the Azure Utilization Records, you first need a customer identifier and a subscription identifier. Em seguida, você chama o Get-PartnerCustomerSubscriptionUtilization.You then call the Get-PartnerCustomerSubscriptionUtilization. Esse comando retornará todos os registros disponíveis para o período de tempo especificado.This command will return all records available for the specified period of time.

# $customerId
# $subscriptionId

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

Solicitação RESTREST request

Sintaxe da solicitaçãoRequest syntax

MétodoMethod URI da solicitaçãoRequest URI
GETGET {baseURL}/v1/Customers/{Customer-Tenant-ID}/subscriptions/{Subscription-ID}/utilizations/Azure? hora de início _ = {hora de início} &_ hora de término = {hora de término} &granularidade = {granularidade} &mostrar _ detalhes = {true}{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 URIURI parameters

Use o caminho e os parâmetros de consulta a seguir para obter os registros de utilização.Use the following path and query parameters to get the utilization records.

NomeName TipoType ObrigatórioRequired DescriçãoDescription
customer-tenant-idcustomer-tenant-id stringstring SimYes Uma cadeia com formato de GUID que identifica o cliente.A GUID-formatted string that identifies the customer.
id da assinaturasubscription-id stringstring SimYes Uma cadeia com formato de GUID que identifica a assinatura.A GUID-formatted string that identifies the subscription.
start_timestart_time Cadeia de caracteres no formato de deslocamento de data/hora UTCstring in UTC date-time offset format SimYes O início do intervalo de tempo que representa quando a utilização foi relatada no sistema de cobrança.The start of the time range that represents when the utilization was reported in the billing system.
end_timeend_time Cadeia de caracteres no formato de deslocamento de data/hora UTCstring in UTC date-time offset format SimYes O fim do intervalo de tempo que representa quando a utilização foi relatada no sistema de cobrança.The end of the time range that represents when the utilization was reported in the billing system.
granularidadegranularity Cadeia de caracteresstring NoNo Define a granularidade das agregações de uso.Defines the granularity of usage aggregations. As opções disponíveis são: daily (padrão) e hourly .Available options are: daily (default) and hourly.
show_detailsshow_details booleanoboolean NoNo Especifica se deve obter os detalhes de uso no nível da instância.Specifies whether to get the instance-level usage details. O padrão é true.The default is true.
tamanhosize númeronumber NoNo Especifica o número de agregações retornadas por uma única chamada de API.Specifies the number of aggregations returned by a single API call. O padrão é 1000.The default is 1000. O máximo é 1000.The max is 1000.

Cabeçalhos de solicitaçãoRequest headers

Para obter mais informações, confira Cabeçalhos REST do Partner Center.For more information, see Partner Center REST headers.

Corpo da solicitaçãoRequest body

NenhumNone

Exemplo de solicitaçãoRequest example

A solicitação de exemplo a seguir produz resultados semelhantes ao que o arquivo de reconciliação mostrará para o período de 7/2-8/1.The following example request produces results similar to what the reconciliation file will show for the period 7/2 - 8/1. Esses resultados podem não corresponder exatamente (consulte a seção API de utilização do Azure para obter detalhes).These results may not match exactly (see the section Azure utilization API for details).

Esta solicitação de exemplo retorna dados de utilização relatados no sistema de cobrança entre 7/2 às 12 horas (UTC) e 8/2 às 12 (UTC).This example request returns utilization data reported in the billing system between 7/2 at 12 AM (UTC) and 8/2 at 12 AM (UTC).

GET https://api.partnercenter.microsoft.com/v1/customers/E499C962-9218-4DBA-8B83-8ADC94F47B9F/subscriptions/FC8F8908-F918-4406-AF13-D5BC0FE41865/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: a687bc47-8d08-4b78-aff6-5a59aa2055c2
X-Locale: en-US
Host: api.partnercenter.microsoft.com

Resposta RESTREST response

Se for bem-sucedido, esse método retornará uma coleção de recursos de registro de utilização do Azure no corpo da resposta.If successful, this method returns a collection of Azure Utilization Record resources in the response body. 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 tentar novamente.If the Azure utilization data isn't yet ready in a dependent system, this method returns an HTTP Status Code 204 with a Retry-After header.

Códigos de êxito e de erro de respostaResponse success and error codes

Cada resposta vem com um código de status HTTP que indica êxito ou falha e informações de depuração adicionais.Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use uma ferramenta de rastreamento de rede para ler o código de status HTTP, o tipo de código de erroe os parâmetros adicionais.Use a network trace tool to read the HTTP status code, error code type, and additional parameters.

Exemplo de respostaResponse example

HTTP/1.1 200 OK
Content-Length: 2630
Content-Type: application/json; charset=utf-8
MS-CorrelationId: a687bc47-8d08-4b78-aff6-5a59aa2055c2
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/ab7e2384-eeee-489a-a14f-1eb41ddd261d/resourcegroups/system.local/providers/Microsoft.Storage/storageaccounts/srphealthaccount",
        "location": "azurestack",
        "partNumber": "",
        "orderNumber": "",
        "additionalInfo": {
          "azureStack.MeterId": "09F8879E-87E9-4305-A572-4B7BE209F857",
          "azureStack.SubscriptionId": "dbd1aa30-e40d-4436-b465-3a8bc11df027",
          "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/ab7e2384-eeee-489a-a14f-1eb41ddd261d/resourcegroups/system.local/providers/Microsoft.Storage/storageaccounts/srphealthaccount",
        "location": "azurestack",
        "partNumber": "",
        "orderNumber": "",
        "additionalInfo": {
          "azureStack.MeterId": "09F8879E-87E9-4305-A572-4B7BE209F857",
          "azureStack.SubscriptionId": "dbd1aa30-e40d-4436-b465-3a8bc11df027",
          "azureStack.Location": "local",
          "azureStack.EventDateTime": "06/05/2017 06:00:00"
        },
        "attributes": {
          "objectType": "AzureUtilizationRecord"
        }
      },

      "links": {
        "self": {
          "uri": "customers/E499C962-9218-4DBA-8B83-8ADC94F47B9F/subscriptions/FC8F8908-F918-4406-AF13-D5BC0FE41865/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"
      }
    }
  ]
}