API de reconciliação de uso classificado diariamente faturado e não cobrado v2 (GA)

Aplica-se a: Partner Center (indisponível no Azure Governamental ou no Azure China 21Vianet.)

Nossa nova API assíncrona oferece uma maneira mais rápida e eficiente de acessar seus dados de cobrança e reconciliação por meio de blobs do Azure. Em vez de manter uma conexão aberta por horas ou processar lotes de 2.000 itens de linha, agora você pode simplificar seu fluxo de trabalho.

As novas APIs de reconciliação de uso classificado diariamente do comércio usam técnicas avançadas, como chave de manobrista e padrões assíncronos de solicitação-resposta . Essas APIs fornecem um token SAS (assinatura de acesso compartilhado) que você pode usar para acessar todos os atributos ou um subconjunto dos dados de reconciliação de uso classificado diariamente.

Nossas APIs usam técnicas otimizadas para aumentar sua eficiência, para que você possa obter resultados mais rápidos com menos esforço. Adote essas APIs para simplificar seu acesso a dados e melhorar sua eficiência geral.

Você pode usar essas APIs para a nuvem pública/global do MS Graph somente agora. Ela ainda não está disponível para o Azure Governamental nem para o Azure China 21Vianet.

Visão geral da API

Para ajudar você a recuperar itens de linha de uso classificado diariamente de novo comércio faturados de forma assíncrona, oferecemos dois endpoints principais da API. Aqui está um guia simplificado para você começar:

Ponto de extremidade do item de linha de uso

Primeiro, use essa API para buscar novos itens de linha de uso diário de comércio . Ao fazer uma solicitação, você recebe um status HTTP 202 e um cabeçalho de localização com uma URL. Sonde essa URL regularmente até obter um status de êxito e uma URL de manifesto.

Ponto de extremidade de status da operação

Em seguida, continue verificando o status da operação chamando essa API em intervalos regulares. Se os dados não estiverem prontos, a resposta incluirá um cabeçalho Retry-After indicando quanto tempo esperar antes de tentar novamente. Depois que a operação for concluída, você receberá um recurso de manifesto com um link de pasta de armazenamento para baixar os dados de uso. A resposta segmenta os arquivos para melhorar a taxa de transferência e permitir o paralelismo de E/S.

Seguindo estas etapas, você pode gerenciar com eficiência seu processo de reconciliação de faturas.

Diagrama de sequência

Aqui está um diagrama de sequência que mostra as etapas para baixar os dados de reconciliação.

Sequência de ação do usuário

Para recuperar itens de linha de reconciliação de uso classificado diariamente para novos comércios , siga estas etapas:

Etapa 1: enviar solicitação

Envie uma solicitação POST para o endpoint da API.

Receber itens de linha de uso classificado diariamente não faturados

Obtenha itens de linha de uso nominal diário não cobrado do novo comércio para o mês atual ou último ou período de faturamento.

Solicitação de API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

Corpo da solicitação

Cabeçalhos da solicitação

Para solicitar cabeçalhos para a API, consulte Confiabilidade e suporte.

Resposta da API

HTTP/1.1 202 Accepted  
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

A API geralmente responde com um status HTTP 202. Você também pode encontrar outros status, dependendo de suas solicitações. Esses status são listados na seção Status de resposta da API padrão.

Receber itens de linha de uso classificado diariamente cobrados

Obtenha itens de linha de uso classificado diariamente cobrados pelo novo comércio para uma fatura para o período de cobrança fechado.

Solicitação de API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Parâmetros de consulta

N/D

Corpo da solicitação

Cabeçalho da solicitação

Cabeçalhos de solicitação para a API. Para saber mais, consulte a confiabilidade e o suporte.

Resposta da API

HTTP/1.1 202 Aceito
Local: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Quando você usa a API, ela normalmente retorna um status HTTP 202. Para outros status possíveis com base em suas solicitações, consulte Status.

Etapa 2: verificar o status da solicitação

Para acompanhar o status de uma solicitação, certifique-se de receber uma resposta HTTP 200 indicando "bem-sucedido" ou "falha". Se for bem-sucedido, você encontrará o URL do manifesto no atributo "resourceLocation". Esse atributo fornece um ponto de extremidade para acessar as informações necessárias.

Obter status da operação

Recupera o status de uma solicitação.

Solicitação de API

GET https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Parâmetros da solicitação

Cabeçalho da solicitação

Para solicitar cabeçalhos para a API, consulte Confiabilidade e suporte.

Corpo da solicitação

N/D

Status da resposta

Além dos status HTTP padrão listados em Status de resposta da API padrão, a API também pode retornar o seguinte status HTTP:

Payload de resposta

A carga de resposta da API inclui os seguintes atributos:

Objeto de localização do recurso

Solicitação de API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Resposta da API

A resposta recomenda aguardar 10 segundos antes de tentar novamente ao processar dados.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

Solicitação de API

(10 segundos após a solicitação anterior...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Resposta da API

A API retorna o status "bem-sucedido" e o URI para "resourceLocation".

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Etapa 3: Baixar itens de linha de reconciliação de uso classificado diariamente do armazenamento de blobs do Azure

Primeiro, você precisa obter o token SAS (assinatura de acesso compartilhado) e o local de armazenamento de blobs. Você pode encontrar esses detalhes nas propriedades "sasToken" e "rootDirectory" da resposta da API de carga útil do manifesto. Em seguida, para baixar e descompactar o arquivo de blob, use o SDK/ferramenta do Armazenamento do Azure. Está no formato JSONLines .

Status de resposta padrão da API

Você pode receber estes status HTTP da resposta da API:

Comparar as versões beta e GA

Confira a tabela de comparação para ver as diferenças entre as versões beta e GA (disponibilidade geral). Se você estiver usando a versão beta, a transição para a versão GA é simples e fácil.

Atributos de item de linha de reconciliação de uso avaliado diariamente

Para comparar os atributos retornados pela API de reconciliação de fatura faturada para os conjuntos de atributos "completos" ou "básicos", consulte a tabela a seguir. Para saber mais sobre esses atributos, consulte esta documentação.

Código de exemplo

Para usar essa API, consulte o link a seguir, que inclui o código de exemplo C#.

Exemplos de API do Partner Center: obter dados de reconhecimento de cobrança.