Paradigma de acesso programático para marketplace comercial

Artigo
07/16/2024

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.

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.
Em caso de sucesso, a API Criar modelo de relatório retorna o QueryId.
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.
Em caso de sucesso, a API Criar modelo de relatório retorna o ReportID.
O aplicativo cliente é notificado no URI de retorno de chamada assim que os dados do relatório estiverem prontos para download.
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.
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

Método	URI da solicitação
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

Cabeçalho da solicitação

Cabeçalho	Tipo	Descrição
Autorização	string	Obrigatória. O token de acesso do Microsoft Entra. O formato é `Bearer <token>`.
Content-Type	`string`	`application/JSON`

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.

Parâmetro	Obrigatório	Descrição	Valores permitidos
`Name`	Sim	Nome amigável da consulta	string
`Description`	Não	Descrição da consulta criada	string
`Query`	Sim	Cadeia de caracteres de consulta com base na necessidade de negócios	string

Observação

Para obter exemplos de consulta personalizada, consulte consultas de exemplo.

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.

Parâmetro	Descrição
`QueryId`	UUID (identificador universalmente exclusivo) da consulta criada
`Name`	Nome fornecido na carga da solicitação durante a criação da consulta
`Description`	Descrição fornecida na carga da solicitação durante a criação da consulta
`Query`	Consulta de relatório personalizada fornecida na carga da solicitação durante a criação da consulta
`Type`	Definir como `userDefined` para consultas criadas manualmente
`User`	ID de usuário usada para criar a consulta
`CreatedTime`	UTC Hora em que a consulta foi criada. Formato: aaaa-MM-ddTHH:mm:ssZ
`TotalCount`	Número de registros na matriz Value
`StatusCode`	Código de resultado Os valores possíveis são 200, 400, 401, 403, 500
`message`	Mensagem do status da execução da API

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

Método	URI da solicitação
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

Cabeçalho da solicitação

Cabeçalho	Tipo	Descrição
Autorização	string	Obrigatória. O token de acesso do Microsoft Entra. O formato é `Bearer <token>`.
Tipo de conteúdo	string	`application/JSON`

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.

Parâmetro	Obrigatório	Descrição	Valores permitidos
`ReportName`	Sim	Nome amigável atribuído ao relatório	String
`Description`	Não	Descrição do relatório criado	String
`QueryId`	Sim	ID de consulta que precisa ser usada para geração de relatório	String
`StartTime`	Sim	Carimbo de data/hora UTC no qual a geração de relatório será iniciada. O formato deve ser: aaaa-MM-ddTHH:mm:ssZ	String
`ExecuteNow`	Não	Esse parâmetro deve ser usado para criar um relatório que é executado apenas uma vez. `StartTime`, `RecurrenceInterval`, `RecurrenceCount`e `EndTime` são ignorados se estiver definido como `true`	Booliano
`QueryStartTime`	Não	Opcionalmente, especifica a hora de início para a consulta que extrai os dados. Esse parâmetro é aplicável somente para o relatório de execução de um tempo que tenha `ExecuteNow` definido como `true`. O formato deve ser: aaaa-MM-ddTHH:mm:ssZ	Carimbo de data/hora como cadeia de caracteres
`QueryEndTime`	Não	Opcionalmente, especifica a hora de início para a consulta que extrai os dados. Esse parâmetro é aplicável somente para o relatório de execução de um tempo que tenha `ExecuteNow` definido como `true`. O formato deve ser: aaaa-MM-ddTHH:mm:ssZ	Carimbo de data/hora como cadeia de caracteres
`RecurrenceInterval`	Sim	Frequência em horas em que o relatório deve ser gerado. O valor mínimo é 1 e o valor máximo é 17520	Inteiro
`RecurrenceCount`	Sim	Número de relatórios a serem gerados. O limite depende do intervalo de recorrência	Inteiro
`Format`	Não	Formato de arquivo do arquivo exportado. O formato padrão é CSV	CSV/TSV
`CallbackUrl`	Não	URL acessível publicamente que pode ser configurada opcionalmente como o destino do retorno de chamada	String
`CallbackMethod`	Não	Método Get/Post que pode ser configurado com URL de retorno de chamada	GET/POST
`EndTime`	Sim	Carimbo de data/hora UTC no qual a geração do relatório terminará. O formato deve ser: aaaa-MM-ddTHH:mm:ssZ	String

Observação

Ao criar o relatório, uma ou EndTime combinação de RecurrenceInterval e RecurrenceCount é obrigatória.

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.

Parâmetro	Descrição
`ReportId`	UUID (identificador universal exclusivo) do relatório criado
`ReportName`	Nome fornecido na carga da solicitação durante a criação do relatório
`Description`	Descrição fornecida na carga útil da solicitação durante a criação do relatório
`QueryId`	ID de consulta fornecida na carga útil da solicitação durante a criação do relatório
`Query`	Texto da consulta que será executada para este relatório
`User`	ID de usuário usada para criar o relatório
`CreatedTime`	Hora UTC em que o relatório foi criado neste formato: aaaa-MM-ddTHH:mm:ssZ
`ModifiedTime`	Hora UTC em que o relatório foi modificado pela última vez neste formato: aaaa-MM-ddTHH:mm:ssZ
`ExecuteNow`	ExecuteNow fornecido na carga útil da solicitação durante a criação do relatório
`queryStartTime`	Hora de início da consulta fornecida na carga da solicitação durante a criação do relatório. Isso é aplicável somente se `ExecuteNow` estiver definido como "True"
`queryEndTime`	Hora de término da consulta fornecida na carga da solicitação durante a criação do relatório. Isso é aplicável somente se `ExecuteNow` estiver definido como "True"
`StartTime`	Hora de início fornecida na carga da solicitação durante a criação do relatório
`ReportStatus`	Status da execução do relatório. Os valores possíveis são Pausado, Ativoe Inativo.
`RecurrenceInterval`	Intervalo de recorrência fornecido na carga útil da solicitação durante a criação do relatório
`RecurrenceCount`	Contagem de recorrência restante para o relatório
`CallbackUrl`	URL de retorno de chamada fornecida na carga da solicitação durante a criação do relatório
`CallbackMethod`	Método de retorno de chamada fornecido na carga da solicitação durante a criação do relatório
`Format`	Formato dos arquivos de relatório fornecidos na carga útil da solicitação durante a criação do relatório
`EndTime`	Hora de término fornecida na carga da solicitação durante a criação do relatório. Isso é aplicável somente se `ExecuteNow` estiver definido como "True"
`TotalRecurrenceCount`	`RecurrenceCount` fornecido na carga útil da solicitação durante a criação do relatório
`nextExecutionStartTime`	Carimbo de data/hora UTC quando a próxima execução do relatório será iniciada
`TotalCount`	Número de registros na matriz Value
`StatusCode`	Código de resultado. Os valores possíveis são 200, 400, 401, 403, 500
`message`	Mensagem do status da execução da API

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.

Importante

Essa API tem parâmetros de consulta padrão definidos para executionStatus=Completed e getLatestExecution=true. Portanto, chamar a API antes da primeira execução bem-sucedida do relatório retornará 404. Execuções pendentes podem ser obtidas pela configuração executionStatus=Pending.

Sintaxe da solicitação

Método	URI da solicitação
Obter	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Cabeçalho da solicitação

Cabeçalho	Tipo	Descrição
Autorização	string	Obrigatória. O token de acesso do Microsoft Entra. O formato é `Bearer <token>`.
Tipo de conteúdo	string	`application/json`

Parâmetro de caminho

Nenhum

Parâmetro de consulta

Nome do Parâmetro	Obrigatório	Type	Descrição
`reportId`	Sim	string	Filtro para obter detalhes de execução apenas de relatórios com `reportId` fornecido neste argumento.
`executionId`	Não	string	Filtro para obter detalhes apenas de relatórios com `executionId` fornecido neste argumento. Múltiplos `executionIds` podem ser especificados separando-os com um ponto-e-vírgula ";".
`executionStatus`	Não	string/enum	Filtro para obter detalhes apenas de relatórios com `executionStatus` fornecido neste argumento. Os valores válidos são: `Pending`, `Running`, `Paused`, e `Completed` O valor padrão é `Completed`.
`getLatestExecution`	Não	boolean	A API retornará detalhes da última execução do relatório. Por padrão, esse parâmetro é definido como `true`. Se optar por passar o valor desse parâmetro como `false`, a API retornará as instâncias de execução dos últimos 90 dias.

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.

Parâmetro	Descrição
`ExecutionId`	UUID (identificador universal exclusivo) da instância de execução
`ReportId`	ID do relatório associada à instância de execução
`RecurrenceInterval`	Intervalo de recorrência fornecido durante a criação do relatório
`RecurrenceCount`	Contagem de recorrência fornecido durante a criação do relatório
`CallbackUrl`	URL de retorno de chamada associada à instância de execução
`CallbackMethod`	Método de retorno de chamada fornecido na carga da solicitação durante a criação do relatório
`Format`	Formato do arquivo gerado no final da execução
`ExecutionStatus`	Status da instância de execução do relatório. Os valores válidos são: `Pending`, `Running`, `Paused`, e `Completed`
`ReportLocation`	Local onde o relatório é baixado.
`ReportAccessSecureLink`	Link pelo qual o relatório pode ser acessado com segurança
`ReportExpiryTime`	Hora UTC após a qual o link do relatório expirará neste formato: aaaa-MM-ddTHH:mm:ssZ
`ReportGeneratedTime`	Hora UTC em que o relatório foi gerado neste formato: aaaa-MM-ddTHH:mm:ssZ
`EndTime`	Hora de término fornecida na carga da solicitação durante a criação do relatório. Isso é aplicável somente se `ExecuteNow` estiver definido como "True"
`TotalRecurrenceCount`	`RecurrenceCount` fornecido na carga útil da solicitação durante a criação do relatório
`nextExecutionStartTime`	Carimbo de data/hora UTC quando a próxima execução do relatório será iniciada
`TotalCount`	Número de conjuntos de itens na Matriz de valores
`StatusCode`	Código de resultado Os valores possíveis são 200, 400, 401, 403, 404 e 500
`message`	Mensagem do status da execução da API

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

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

Compartilhar via

Paradigma de acesso programático para marketplace comercial

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

Criar API Criar relatório

Criar API de relatório

Obter API de execuções de relatório

Comentários

Recursos adicionais

Compartilhar via

Paradigma de acesso programático para marketplace comercial

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

Criar API Criar relatório

Criar API de relatório

Obter API de execuções de relatório

Conteúdo relacionado

Comentários

Recursos adicionais