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 o Create Report Query API. Como alternativa, você pode usar um modelo de relatório (QueryId) da lista de consultas do sistema.
2. Se for bem-sucedida, a API Criar Modelo de Relatório retornará o QueryId.
3. Em seguida, a aplicação cliente chama a Create Report API usando o QueryID juntamente com a data de início do relatório, intervalo de repetição, recorrência e um URI de retorno de chamada opcional.
4. Se for bem-sucedido, o Create Report API retornará o ReportID.
5. A aplicação cliente é notificada na URI de callback logo que os dados do relatório estejam prontos para transferência.
6. Em seguida, o aplicativo cliente usa a API Obter Execuções de Relatório para consultar o status do relatório com o Report ID e o intervalo de datas.
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 pode usar para criar relatórios, também pode criar as suas próprias consultas com base nas suas necessidades empresariais. 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 o Criar API de Relatório diretamente usando o 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 de solicitação

Cabeçalho da solicitação

Parâmetro Caminho

Nenhum

Parâmetro de consulta

Nenhum

Exemplo de carga útil de solicitação

{
    "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.

Exemplo de resposta

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 com êxito um modelo de relatório personalizado e receber o QueryID como parte da resposta Criar Consulta de Relatório, esta API pode ser chamada para agendar a execução de uma consulta 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 de solicitação

Cabeçalho da solicitação

Parâmetro de Caminho

Nenhum

Parâmetro de consulta

Nenhum

Exemplo de carga útil de solicitação

{
  "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.

Exemplo de resposta

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 do Create Report API. 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 de solicitação

Cabeçalho da solicitação

Parâmetro de Caminho

Nenhum

Parâmetro de consulta

Solicitar de carga útil

Nenhum

Exemplo de resposta

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 estado de execução Completed será exibido. 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 através da URL da API Swagger .

Conteúdo relacionado

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