Paradigma de acesso programático para marketplace 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 relatório de consulta. Como alternativa, é possível usar um modelo de relatório (QueryId) na lista de consultas do sistema.
2. Em caso de sucesso, a API Criar modelo de relatório retorna o QueryId.
3. Em seguida, o aplicativo cliente chama a API Criar relatório usando o QueryID junto com a data de início do relatório, Intervalo de repetição, Recorrência e um URI de retorno de chamada opcional.
4. Em caso de sucesso, a API Criar modelo de relatório retorna o ReportID.
5. O aplicativo cliente é notificado no URI de retorno de chamada assim que os dados do relatório estiverem prontos para download.
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. Em caso de sucesso, o link de download do relatório é retornado e o aplicativo pode iniciar o download dos dados.

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

Embora forneçamos consultas de sistema que podem ser usadas para criar relatórios, também é possível criar suas próprias consultas com base em nas necessidades de seus negócios. Para saber mais sobre consultas personalizadas, consulte Especificação de consulta personalizada.

Criar API Criar relatório

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

Também é possível usar as consultas do sistema que fornecemos. Quando os 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 o Uso normalizado e encargos financeiros estimados para SKUs PAGAS do conjunto de dados ISVUsage do último mês.

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro de caminho

Nenhum

Parâmetro de consulta

Nenhum

Exemplo de carga 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 dos elementos da carga de solicitação.

Resposta de exemplo

A carga de solicitação é estrutura conforme a seguir:

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

Exemplo de conteúdo da 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 dos elementos da resposta.

Criar API de relatório

Ao criar um modelo de relatório personalizado com êxito e receber o QueryID como parte da resposta de Criar consulta de relatório, essa API pode ser chamada para agendar uma consulta a ser executada em intervalos regulares. É possível definir uma frequência e um agendamento para o relatório a ser entregue. Para consultas do sistema que fornecemos, a API criar relatório também pode ser chamada com QueryId.

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro de caminho

Nenhum

Parâmetro de consulta

Nenhum

Exemplo de carga 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 dos elementos da carga de solicitação.

Resposta de exemplo

A carga de solicitação é estrutura conforme a seguir:

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

Carga 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 dos elementos da resposta.

Obter API de execuções de relatório

É possível 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 retornará o link de download do relatório se o relatório estiver pronto para download. Caso contrário, o método retornará o status. Também é possível usar essa API para obter todas as execuções que ocorreram para um determinado relatório.

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro de caminho

Nenhum

Parâmetro de consulta

Carga de solicitação

Nenhum

Resposta de exemplo

A carga de solicitação é estrutura conforme a seguir:

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

Exemplo de conteúdo da 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
}

Depois que a execução do relatório for concluída, o status de execução Completed será mostrado. É possível baixar o relatório selecionando a URL no reportAccessSecureLink.

Glossário

Principais definições dos elementos na resposta.

É possível experimentar as APIs por meio da URL da API do Swagger.

Conteúdo relacionado

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