Obter itens de linha de reconciliação não faturados de forma assíncrona API v2 (GA)

Aplica-se a: Partner Center (indisponível na China 21Vianet e para dados de comércio herdados)

Você pode usar essa API para obter uma coleção de detalhes para itens de linha de fatura não faturados (também conhecidos como itens de linha de cobrança abertos).

Nossa nova API assíncrona oferece uma maneira mais rápida e eficiente de acessar seus dados de cobrança e reconciliação não faturados 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, reduzir a carga do servidor e melhorar os tempos de processamento de dados.

A nova API de reconciliação de fatura sem faturas de comércio usa técnicas avançadas, como chave de manobrista e padrões assíncronos de solicitação-resposta . O padrão de chave de manobrista dá suporte ao acesso seguro aos recursos sem compartilhar credenciais, enquanto o padrão assíncrono de solicitação-resposta permite uma comunicação eficiente entre sistemas.

Essa API fornece 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 fatura não faturados. Esse token aprimora a segurança concedendo acesso por tempo limitado e oferece flexibilidade no gerenciamento de permissões de acesso a dados.

Ao adotar nossas APIs otimizadas, você pode obter resultados mais rápidos com menos esforço, simplificar o acesso a dados e melhorar a eficiência geral. Abrace essas ferramentas para simplificar seu fluxo de trabalho e gerenciar permissões com mais eficiência.

Entender a arquitetura

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

Principais componentes

Proteger o acesso com o padrão de chave de manobrista

O padrão de chave de manobrista fornece acesso seguro e limitado aos seus dados de cobrança não faturados. Semelhante a como uma chave de manobrista permite que alguém conduza seu carro sem acessar o tronco, esse padrão garante o controle de acesso granular. Em vez de compartilhar credenciais, um token SAS (assinatura de acesso compartilhado) concede acesso limitado e limitado 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 do padrão assíncrono solicitação-resposta

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

A natureza assíncrona da API significa que você faz uma solicitação e o sistema a processa em segundo plano. Essa resposta de solicitação assíncrona usa recursos com eficiência, reduz a carga do servidor e minimiza tempos limite e falhas comuns com a 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 não faturados ou limitam o acesso a subconjuntos específicos. Essa granularidade permite que as organizações adaptem o acesso a dados de acordo com políticas internas e requisitos regulatórios, aprimorando a segurança e a conformidade.

Fluxo de trabalho simplificado e tempos de processamento de dados aprimorados

O padrão assíncrono de 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 tempos de processamento aprimorados, simplificando a integração de dados de cobrança e reconciliação não faturados em sistemas e fluxos de trabalho existentes.

Benefícios

• Benefícios de desempenho

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

  • Faça uma solicitação inicial rápida.
  • Receba um token de acesso seguro.
  • Processe dados em seu próprio ritmo.
  • Acesse exatamente o que você precisa quando precisar.

• Melhorias de segurança

  O padrão de chave de manobrista, implementado por meio de tokens SAS, fornece:

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

• Vantagens arquitetônicas

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

  • Aceita sua solicitação.
  • Manipula a tarefa em segundo plano.
  • Notifica você quando tudo está pronto.

Adotar 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 o controle de acesso seguro e mecanismos de recuperação eficientes, você obtém melhores resultados com menos esforço, levando a uma melhor eficiência operacional.

Em conclusão, a nova API assíncrona para acessar dados de cobrança e reconciliação não faturados 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.

Permitir que seu aplicativo acesse com segurança os dados de cobrança do parceiro

Para permitir que seu aplicativo acesse dados de cobrança de parceiros, siga este link e familiarize-se com os conceitos básicos de autenticação e autorização do Microsoft Graph. Essa etapa é crucial, pois garante que seu aplicativo possa acessar com segurança os dados necessários.

Registre seu aplicativo e atribua a permissão PartnerBilling.Read.All

Você pode atribuir a permissão "PartnerBilling.Read.All" usando o portal do Azure ou o centro de administração do Microsoft Entra. Ao concluir essas etapas, você ajuda a garantir que seu aplicativo tenha o acesso necessário aos dados de cobrança do parceiro. Aqui está como:

1. Registre seu aplicativo na home page do Microsoft Entra na seção Registros de aplicativo.
2. Conceda a permissão necessária acessando a página do Aplicativo Microsoft Entra. Na seção de permissões de API, selecione Adicionar uma permissão e escolha o escopo PartnerBilling.Read.All .

Saiba mais sobre os principais pontos de extremidade da API

Para ajudá-lo a recuperar novos itens de linha de reconciliação de fatura de comércio sem faturas de forma assíncrona, oferecemos dois pontos de extremidade de API principais. Esses pontos de extremidade ajudam você a gerenciar com eficiência o processo de reconciliação de fatura não faturado. Siga este guia simplificado para começar rapidamente.

Usar o ponto de extremidade de reconciliação de fatura não faturado

Primeiro, use essa API para buscar novos itens de linha de reconciliação de fatura sem faturas. Ao fazer uma solicitação, você recebe um status HTTP 202 e um cabeçalho de localização com uma URL. Sondar essa URL regularmente até obter um status de êxito e uma URL de manifesto.

Usar o 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 reconciliação. A resposta segmenta os arquivos para aprimorar a taxa de transferência e permitir paralelismo de E/S.

Examinar o diagrama de sequência

Aqui está um diagrama de sequência que mostra as etapas para baixar novos dados de reconciliação de fatura sembilbilização de comércio.

Siga a sequência de ação do usuário para recuperar dados de reconciliação de fatura não faturados

Esta é a sequência de ação do usuário para recuperar dados de reconciliação de fatura não faturados:

1. Enviar uma solicitação POST
2. Verificar o status da solicitação
3. Baixar itens de linha de reconciliação não faturados do armazenamento de blobs do Azure

Enviar uma solicitação POST

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

Obter itens de linha de reconciliação de fatura sem fatura

Obtenha os itens de linha de reconciliação de fatura não faturados.

Solicitação de API

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

Accept: application/json

Content-Type: application/json

{
"attributeSet": "full",
"billingPeriod": "current",
"currencyCode": "USD"
}

Parâmetros de consulta

N/A

Corpo da solicitação

Cabeçalhos da solicitação

Solicite cabeçalhos para a API usando as etapas listadas nas práticas recomendadas para usar o Microsoft Graph. Seguindo essas diretrizes, você garante a confiabilidade e o suporte para seu aplicativo. Sua atenção aos detalhes nesta etapa é crucial para a integração perfeita e o desempenho ideal.

Resposta à 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 Standard .

Verificar o status da solicitação

Para acompanhar o status de uma solicitação, verifique se você recebeu uma resposta HTTP 200 que é um código de status padrão que indica "bem-sucedido" ou "falhou". Se tiver êxito, você encontrará a URL do manifesto no atributo "resourceLocation". Esse 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.

Solicitação de API

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

Parâmetros de solicitação

Cabeçalho da solicitação

Solicite cabeçalhos para a API usando as etapas listadas nas práticas recomendadas para usar o Microsoft Graph. Seguindo essas diretrizes, você garante a confiabilidade e o suporte para seu aplicativo. Sua atenção aos detalhes nesta etapa é crucial para a integração perfeita e o desempenho ideal.

Corpo da solicitação

N/A.

Status da resposta

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

Payload da resposta

O conteúdo da resposta à 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 à API

A resposta recomenda esperar 10 segundos antes de tentar novamente quando seus dados ainda estiverem sendo processados.

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 à 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 não faturados do armazenamento de blobs do Azure

Primeiro, você precisa obter o token SAS (assinatura de acesso compartilhado) e o local de armazenamento de blobs (combinar o diretório raiz e o nome do blob). Encontre esses detalhes na sasTokenrootDirectoryresposta da API de conteúdo do manifesto e blobs das propriedades da resposta à API de conteúdo do manifesto.

Para continuar, siga estas etapas:

1. Baixe o arquivo de blob usando o SDK/ferramenta do Armazenamento do Azure.
2. Descompacte o arquivo, que está no formato JSONLines .

Status de resposta da API padrão

Você pode obter os seguintes status HTTP da resposta à API:

Comparar atributos básicos e completos de reconciliação sembilos

Para comparar os atributos retornados pela API de reconciliação de fatura não fatura para os conjuntos de atributos "completos" ou "básicos", consulte esta tabela. Para saber mais sobre esses atributos e seus significados, veja como usar o arquivo de reconciliação.

Código de exemplo

Se você precisar de assistência para migrar para essa API, consulte o link que inclui o código de exemplo do C#.

Exemplos de API para obter dados de reconciliação não faturados do Partner Center.

Conteúdo relacionado

• SDK/ferramenta de Armazenamento do Azure
• Usar a API do Microsoft Graph para exportar dados de cobrança de parceiros