Paradigma de acesso programático para mercado comercial

Este diagrama mostra o padrão de chamada de API usado para criar um novo modelo de relatório, agendar o relatório personalizado e recuperar dados de falha.

Figura 1: Fluxo de alto nível do padrão de chamada de API

Esta lista fornece mais detalhes sobre a Figura 1.

1. O Aplicativo Cliente pode definir o esquema/modelo de relatório personalizado chamando a API Criar Consulta de Relatório. Como alternativa, você pode usar um modelo de relatório (QueryId) na lista de consultas do sistema.
2. Se for bem-sucedido, a API Criar Modelo de Relatório retornará o QueryIdarquivo .
3. Em seguida, o aplicativo cliente chama a API Criar Relatório usando a data de início do QueryID relatório, Intervalo de Repetição, Recorrência e um URI de retorno de chamada opcional.
4. Quando for bem-sucedida, a API Criar Relatório retornará o ReportIDarquivo .
5. O aplicativo cliente é notificado no URI de retorno de chamada assim que os dados do relatório estão prontos para download.
6. Em seguida, o aplicativo cliente usa a API Get Report Executions para consultar o status do relatório com o Report ID intervalo de datas e .
7. Se for bem-sucedido, o link de download do relatório é retornado e o aplicativo pode iniciar o download dos dados.

Especificação da linguagem de consulta de relatório

Embora forneçamos consultas de sistema que você pode usar para criar relatórios, você também pode criar suas próprias consultas com base em suas necessidades de negócios. Para saber mais sobre consultas personalizadas, consulte Especificação de consulta personalizada.

Criar API de consulta de relatório

Essa API ajuda a criar consultas personalizadas que definem o conjunto de dados do qual as colunas e métricas precisam ser exportadas. A API oferece a flexibilidade de criar um novo modelo de relatório com base nas suas necessidades de negócios.

Você também pode usar as consultas do sistema que fornecemos. Quando modelos de relatório personalizados não são necessários, você pode chamar a API Criar Relatório diretamente usando os QueryIds das consultas do sistema que fornecemos.

O exemplo a seguir mostra como criar uma consulta personalizada para obter Uso Normalizado e Encargos Financeiros Estimados para SKUs PAGOS do conjunto de dados ISVUsage do último mês.

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro Path

Nenhuma

Parâmetro de consulta

Nenhuma

Exemplo de solicitação de carga útil

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

Glossário

Esta tabela fornece as principais definições de elementos na carga útil da solicitação.

Resposta de amostra

A carga útil de resposta está estruturada da seguinte forma:

Códigos de resposta: 200, 400, 401, 403, 500

Exemplo de carga útil de resposta:

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

Glossário

Esta tabela fornece as principais definições de elementos na resposta.

Criar API de relatório

Ao criar um modelo de relatório personalizado com êxito e receber a QueryID resposta como parte de Criar Consulta de Relatório, essa API pode ser chamada para agendar uma consulta a ser executada em intervalos regulares. Você pode definir uma frequência e um cronograma para que o relatório seja entregue. Para consultas de sistema que fornecemos, a API Create Report também pode ser chamada com QueryId.

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro Path

Nenhuma

Parâmetro de consulta

Nenhuma

Exemplo de solicitação de carga útil

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

Glossário

Esta tabela fornece as principais definições de elementos na carga útil da solicitação.

Resposta de amostra

A carga útil de resposta está estruturada da seguinte forma:

Código de resposta: 200, 400, 401, 403, 404, 500

Carga útil de resposta:

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "user": "142344300",
            "createdTime": "2024-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2024-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": "https://<SampleCallbackUrl>",
            "callbackMethod": "GET",
            "format": "csv"
    }
  ],
  "TotalCount": 1,
  "Message": "Report created successfully",
  "StatusCode": 200
}

Glossário

Esta tabela fornece as principais definições de elementos na resposta.

Obter API de execuções de relatório

Você pode usar esse método para consultar o status de uma execução de relatório usando o ReportId recebido da API Criar Relatório. O método retorna o link de download do relatório se o relatório estiver pronto para download. Caso contrário, o método retorna o status. Você também pode usar essa API para obter todas as execuções que aconteceram para um determinado relatório.

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro Path

Nenhuma

Parâmetro de consulta

Solicitar carga útil

Nenhuma

Resposta de amostra

A carga útil de resposta está estruturada da seguinte forma:

Códigos de resposta: 200, 400, 401, 403, 404, 500

Exemplo de carga útil de resposta:

{
    "value": [
        {
            "executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 4,
            "recurrenceCount": 10,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Completed",
            "reportAccessSecureLink": "https://<path to report for download>",
            "reportExpiryTime": null,
            "reportGeneratedTime": "2021-01-13T14:40:46Z"
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

Quando a execução do relatório estiver concluída, o status Completed de execução será mostrado. Você pode baixar o relatório selecionando o URL no reportAccessSecureLink.

Glossário

Principais definições dos elementos da resposta.

Você pode experimentar as APIs por meio da URL da API do Swagger.

Conteúdos relacionados

• Faça sua primeira chamada de API para relatórios do Marketplace Insights