API de reconciliação de uso nominal diária faturada e não faturada v2 (GA)

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

Entenda a arquitetura

A nova API assíncrona oferece avanços significativos na forma como lidamos com o acesso a dados de faturamento e reconciliação. Essa abordagem resolve desafios associados aos métodos síncronos tradicionais, como a manutenção de conexões de longa duração e o processamento de grandes lotes de dados. Aqui estão os principais benefícios e mecanismos desta API:

Componentes-chave

Acesso seguro com padrão de chave de manobrista

O padrão de chave de manobrista fornece acesso seguro e limitado aos seus dados de faturamento. Semelhante a como uma chave de manobrista permite que alguém dirija seu carro sem acessar o porta-malas, esse padrão garante um controle de acesso granular. Em vez de compartilhar credenciais, um token de assinatura de acesso compartilhado (SAS) concede acesso limitado e limitado ao tempo a recursos específicos. Esse padrão reduz o risco de acesso não autorizado, configurando tempos de expiração precisos e permissões de acesso.

Eficiência aprimorada por meio de um padrão assíncrono de solicitação-resposta

Pense nisso como pedir em um restaurante movimentado. Em vez de esperar no balcão, você recebe uma campainha e pode fazer outras coisas enquanto seu pedido é preparado. Quando os dados estiverem prontos, o sistema notifica-o.

A natureza assíncrona da API significa que você faz uma solicitação e o sistema a processa em segundo plano. Esses pedidos e respostas assíncronos usam recursos de forma eficiente, reduzem a carga do servidor e minimizam tempos limite e falhas comuns à recuperação de dados síncrona.

Flexibilidade nas permissões de acesso a dados

Os tokens SAS oferecem flexibilidade no gerenciamento de permissões de acesso a dados. Você pode gerar tokens que concedem acesso a todos os atributos dos dados de reconciliação de fatura faturada ou limitam o acesso a subconjuntos específicos. Essa granularidade permite que as organizações adaptem o acesso aos dados de acordo com políticas internas e requisitos regulamentares, aprimorando a segurança e a conformidade.

Fluxo de trabalho simplificado e tempos de processamento de dados melhorados

O padrão assíncrono solicitação-resposta simplifica o processamento de dados permitindo acesso dinâmico em vez de lotes fixos de 2.000 itens de linha. Essa abordagem leva a resultados mais rápidos e melhores tempos de processamento, simplificando a integração de dados de faturamento e reconciliação em sistemas e fluxos de trabalho existentes.

Benefícios

1. Benefícios de desempenho

   Em vez de manter conexões de longa duração e processar lotes fixos, o novo sistema permite:

   • Faça um pedido inicial rápido.
   • Receba um token de acesso seguro.
   • Processe dados ao seu próprio ritmo.
   • Acesse exatamente o que você precisa quando precisar.

2. Melhorias de segurança

   O padrão de chave valet, implementado através de tokens SAS, fornece:

   • Acesso limitado no tempo.
   • Permissões restritas.
   • Eliminação do compartilhamento ou armazenamento de credenciais permanentes.
   • Controle de acesso refinado.

3. Vantagens arquitetônicas

   O padrão assíncrono solicitação-resposta age como um assistente pessoal que:

   • Aceita o seu pedido.
   • Manipula a tarefa em segundo plano.
   • Notifica quando tudo estiver pronto.

Adote APIs otimizadas para melhorar o desempenho

A adoção dessas APIs otimizadas simplifica o fluxo de trabalho e melhora o desempenho geral no gerenciamento de dados. Usando controle de acesso seguro e mecanismos de recuperação eficientes, você obtém melhores resultados com menos esforço, levando a uma maior eficiência operacional.

Em conclusão, a nova API assíncrona para acessar dados de cobrança e reconciliação por meio de blobs do Azure é uma ferramenta poderosa. Ele oferece acesso seguro e eficiente a dados financeiros, simplificando fluxos de trabalho, reduzindo cargas de servidor e melhorando os tempos de processamento, tudo com alta segurança e conformidade.

Por enquanto, você só pode usar essas APIs para a nuvem global pública do MS Graph. Eles ainda não estão disponíveis para o Azure Government ou Azure China.

Permitir que seu aplicativo acesse os dados de faturamento do parceiro

Para permitir que a sua aplicação aceda aos dados de faturação do parceiro, clique nesta ligação e familiarize-se com as noções básicas de autenticação e autorização de para o Microsoft Graph. Esta etapa é crucial, pois garante que seu aplicativo possa acessar com segurança os dados necessários.

Atribuir a permissão "PartnerBilling.Read.All"

Atribua a permissão "PartnerBilling.Read.All" usando o portal do Azure ou o centro de administração do Microsoft Entra. Estas etapas garantem que seu aplicativo tenha o acesso necessário aos dados de cobrança do parceiro.

1. Registe a sua aplicação na página inicial do Microsoft Entra na secção Registos de aplicações.
2. Conceda a permissão necessária acessando a página do Microsoft Entra App. Na seção de permissões da API, selecione Adicionar uma permissão e escolha o âmbito de PartnerBilling.Read.All.

Entenda as diferenças entre as versões beta e GA

Se você estiver usando nossa versão beta, é provável que ache a transição para a versão de disponibilidade geral (GA) suave e intuitiva. Para ajudá-lo a entender as atualizações e melhorias, recomendamos comparar as versões beta e GA. Compreender essas atualizações ajuda a maximizar os novos recursos e melhorias disponíveis na versão GA.

Compreender e usar os endpoints da API

Para ajudá-lo a recuperar novos itens de linha de uso diários de comércio faturados de forma assíncrona, oferecemos dois pontos de extremidade de API principais. Siga este guia simplificado para começar rapidamente.

Utilize o endpoint de item de linha

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

Usar o endpoint de status da operação

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

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. Quando 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 paralelismo de E/S.

Revise o diagrama de sequência de dados de reconciliação

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

Siga a sequência de ação do usuário

Aqui estão as etapas da sequência de ação do usuário para recuperar novos itens de linha de reconciliação de uso diário de comércio avaliado:

• Enviar um pedido
• Verificar o estado do pedido
• Descarregar os itens de linha de reconciliação do armazenamento de blobs do Azure

Submeter um pedido

Envie uma solicitação POST para o ponto de extremidade da API.

Obter itens de linha de uso com classificação diária não faturada

Obtenha novos itens de linha de uso diário não faturados para o mês ou período de faturamento atual ou último do calendário.

Pedido da 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 do pedido

Cabeçalhos do pedido

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 estão listados na seção Status de resposta padrão da API.

Obter itens de linha de uso classificados diariamente cobrados

Obtenha novos itens de linha de uso diários faturados diariamente para uma fatura para o período de faturamento fechado.

Pedido da API

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

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

Parâmetros de consultas

N/A

Corpo do pedido

Cabeçalho do pedido

Solicitar cabeçalhos para a API. Para saber mais, consulte a confiabilidade e o suporte.

Resposta da API

HTTP/1.1 202 Aceito
Localização: 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 obter outros status possíveis com base nas suas solicitações, consulte status.

Verificar o estado do pedido

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

Obter o status da operação

Recupera o status de uma solicitação.

Pedido da API

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

Parâmetros de solicitação

Cabeçalho do pedido

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

Corpo do pedido

N/A.

Estado 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:

Carga útil de resposta

A carga útil de resposta da API inclui os seguintes atributos:

Objeto de local de recurso

Pedido da 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"  
}

Pedido da API

(10 segundos após o pedido 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 de "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"

            }

        \]

    }

}

Baixar itens de linha de reconciliação do armazenamento de blobs do Azure

Primeiro, você precisa obter o token de assinatura de acesso compartilhado (SAS) e o local de armazenamento de blob (combine o diretório raiz e o nome do blob). Você pode encontrar esses detalhes no sasToken, rootDirectorye blobs propriedades da resposta da API de carga útil de manifesto.

Para continuar, siga estes passos:

1. Baixe o ficheiro blob utilizando o SDK ou ferramenta de Armazenamento Azure .
2. Descompacte o arquivo, que está no formato JSONLines.

Compreender os status de resposta padrão da API

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

Compare as versões beta e GA

Confira a tabela de comparação a seguir para ver as diferenças entre as versões beta e geralmente disponível (GA). Se você estiver usando atualmente a versão beta, a transição para a versão GA provavelmente é simples e fácil.

Compare os atributos de conciliação de uso diário avaliados de forma básica e completa

Para comparar os atributos retornados pela API de reconciliação de utilização faturada ou não faturada para os conjuntos de atributos "completo" ou "básico", consulte esta tabela. Para obter mais informações sobre esses atributos e seus significados, consulte os Campos de no arquivo de reconciliação de uso avaliado diariamente.

Código de exemplo

Se precisar de ajuda com a migração para essa API, consulte o link que inclui o código de exemplo em C#.

Exemplos de API do Partner Center: obtenha dados de reconhecimento de faturamento.

Conteúdo relacionado

• API do Microsoft Graph para exportar dados de faturamento de parceiros
• SDK de Armazenamento/ferramenta do Azure