Paradigma de acesso programático para mercado comercial

Artigo
06/14/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 Consulta de Relatório. Como alternativa, você pode usar um modelo de relatório (QueryId) na lista de consultas do sistema.
Se for bem-sucedido, a API Criar Modelo de Relatório retornará o QueryIdarquivo .
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.
Quando for bem-sucedida, a API Criar Relatório retornará o ReportIDarquivo .
O aplicativo cliente é notificado no URI de retorno de chamada assim que os dados do relatório estão prontos para download.
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 .
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

Método	URI do pedido
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

Cabeçalho da solicitação

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

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.

Parâmetro	Necessário	Description	Valores permitidos
`Name`	Sim	Nome amigável da consulta	string
`Description`	Não	Descrição da consulta criada	string
`Query`	Sim	Seqüência de caracteres de consulta com base na necessidade comercial	string

Nota

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

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.

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

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

Método	URI do pedido
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

Cabeçalho da solicitação

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

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.

Parâmetro	Necessário	Description	Valores permitidos
`ReportName`	Sim	Nome amigável atribuído ao relatório	String
`Description`	Não	Descrição do relatório criado	Cadeia (de carateres)
`QueryId`	Sim	ID de consulta que precisa ser usada para geração de relatório	Cadeia (de carateres)
`StartTime`	Sim	Carimbo de data/hora UTC no qual a geração do relatório começará. 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 isso estiver definido como `true`	Boolean
`QueryStartTime`	Não	Opcionalmente, especifica a hora de início da consulta que extrai os dados. Este parâmetro é aplicável apenas para um relatório de execução único 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 término da consulta que extrai os dados. Este parâmetro é aplicável apenas para um relatório de execução único 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	Número inteiro
`RecurrenceCount`	Sim	Número de relatórios a gerar. O limite depende do intervalo de recorrência	Número 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 de retorno de chamada	String
`CallbackMethod`	Não	Método Get/Post que pode ser configurado com URL de retorno de chamada	OBTER/PUBLICAR
`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

Nota

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

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.

Parâmetro	Description
`ReportId`	UUID (identificador universalmente exclusivo) do relatório criado
`ReportName`	Nome fornecido na carga útil 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 de consulta que será executado para este relatório
`User`	ID de usuário usado para criar o relatório
`CreatedTime`	UTC Hora em que o relatório foi criado neste formato: aaaa-MM-ddTHH:mm:ssZ
`ModifiedTime`	Hora UTC O relatório foi modificado pela última vez neste formato: aaaa-MM-ddTHH:mm:ssZ
`ExecuteNow`	Parâmetro 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 útil da solicitação durante a criação do relatório. Isso só é aplicável se `ExecuteNow` estiver definido como "True"
`queryEndTime`	Hora de término da consulta fornecida na carga útil da solicitação durante a criação do relatório. Isso só é aplicável se `ExecuteNow` estiver definido como "True"
`StartTime`	Hora de início fornecida na carga útil da solicitação durante a criação do relatório
`ReportStatus`	Status da execução do relatório. Os valores possíveis são Paused, Ative e Inative.
`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 útil da solicitação durante a criação do relatório
`CallbackMethod`	Método de retorno de chamada fornecido na carga útil 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 útil da solicitação durante a criação do relatório. Isso só é aplicável 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 Valor
`StatusCode`	Código do resultado. Os valores possíveis são 200, 400, 401, 403, 500
`message`	Mensagem de status da execução da API

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.

Importante

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

Sintaxe da solicitação

Método	URI do pedido
Obtenção	`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	Description
Autorização	string	Obrigatório. O token de acesso do Microsoft Entra. O formato é `Bearer <token>`.
Tipo do conteúdo	string	`application/json`

Parâmetro Path

Nenhuma

Parâmetro de consulta

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

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.

Parâmetro	Description
`ExecutionId`	UUID (identificador universalmente exclusivo) da instância de execução
`ReportId`	ID do relatório associado à instância de execução
`RecurrenceInterval`	Intervalo de recorrência fornecido durante a criação do relatório
`RecurrenceCount`	Contagem de recorrência fornecida 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 útil da solicitação durante a criação do relatório
`Format`	Formato do ficheiro 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 através do 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 útil da solicitação durante a criação do relatório. Isso só é aplicável 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 dados na matriz Valor
`StatusCode`	Código de Resultado Os valores possíveis são 200, 400, 401, 403, 404 e 500
`message`	Mensagem de status da execução da API

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

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

Partilhar via

Paradigma de acesso programático para mercado comercial

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

Criar API de consulta de relatório

Criar API de relatório

Obter API de execuções de relatório

Comentários

Recursos adicionais

Partilhar via

Paradigma de acesso programático para mercado comercial

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

Criar API de consulta de relatório

Criar API de relatório

Obter API de execuções de relatório

Conteúdos relacionados

Comentários

Recursos adicionais