Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 escolher um modelo de relatório (QueryId) nos exemplos da biblioteca de modelos de relatório em Lista de consultas do sistema para acesso programático do Partner Insights.
- Em caso de êxito, a API Criar Consulta de Relatório retorna o QueryId.
- Em seguida, o aplicativo cliente precisa chamar a API Create Report usando o QueryId junto com a data de início do relatório, o Intervalo de Repetição, a Recorrência e um URI de retorno de chamada opcional.
- Em caso de êxito, a API Criar Relatório retorna o ReportId.
- O aplicativo cliente é notificado na URL de retorno de chamada assim que os dados do relatório estão 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 a ID do Relatório e o intervalo de datas.
- Em caso de êxito, o link de download do relatório é retornado e o aplicativo pode iniciar o download dos dados.
Especificação da linguagem de consulta do 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 nas necessidades de sua empresa. Para saber mais sobre consultas personalizadas, consulte Especificação de consulta personalizada.
Criar API de consulta de relatório
A 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 necessidades da sua empresa.
Você também pode usar as consultas do sistema que fornecemos. Quando os modelos de relatório personalizados não são necessários, você pode chamar Criar API de Relatório diretamente usando os QueryIds das consultas do sistema fornecidas.
O exemplo a seguir mostra como criar uma consulta personalizada para obter os 10 principais clientes por receita no mês passado.
Sintaxe da solicitação
Método | URI de solicitação |
---|---|
PUBLICAR | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries |
Cabeçalho da solicitação
Cabeçalho | Tipo | Descrição |
---|---|---|
Autorização | corda | Obrigatório O token de acesso do Microsoft Entra. O formato é Bearer <token> . |
Tipo de conteúdo | corda | Application/JSON |
Parâmetro de caminho
Nenhum
Parâmetro de consulta
Nenhum
Exemplo de conteúdo de solicitação
{
"Name": "CustomersRevenueQuery",
"Description": "Query to get top 10 customers by revenue for last month",
"Query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH"
}
Glossário de solicitação
Esta tabela fornece as principais definições de elementos na carga útil da solicitação.
Parâmetro | Obrigatório | Descrição | Valores permitidos |
---|---|---|---|
Nome | Sim | Nome amigável da consulta | corda |
Descrição | Não | Descrição do que a consulta retorna | corda |
Consulta | Sim | Cadeia de caracteres de consulta de relatório | Tipo de dados: string Consulta personalizada com base na necessidade de negócios |
Observação
Para obter exemplos de consulta personalizados, consulte Exemplos de consultas de exemplo.
Resposta de exemplo
O conteúdo da resposta é estruturado da seguinte maneira:
Códigos de resposta: 200, 400, 401, 403, 500
Exemplo de conteúdo da resposta:
{
"value": [
{
"queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"name": "CustomersRevenueQuery",
"description": "Query to get top 10 customers by revenue for last month",
"query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
"type": "userDefined",
"user": "GAUser@PITEST2.onmicrosoft.com",
"createdTime": "2021-03-30T12:52:39Z"
}
],
"nextLink": null,
"totalCount": 1,
"message": "Query created successfully",
"statusCode": 200,
"dataRedacted": false
}
Glossário de resposta
Esta tabela fornece as principais definições de elementos na carga útil da solicitação.
Parâmetro | Descrição |
---|---|
QueryId | UUID (identificador universalmente exclusivo) da consulta que você criou |
Nome | Nome amigável dado à consulta na carga da solicitação |
Descrição | Descrição fornecida durante a criação da consulta |
Consulta | Consulta de relatório passada como entrada durante a criação da consulta |
Tipo | Definir como userDefined |
Utilizador | ID do usuário usado para criar a consulta |
CreatedTime | UTC Hora em que a consulta foi criada neste formato: aaaa-MM-ddTHH:mm:ssZ |
ContagemTotal | Número de conjuntos de dados na matriz Value |
CódigoDeStatus | Código de resultado Os valores possíveis são 200, 400, 401, 403, 500 |
mensagem | 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 o QueryID como parte da resposta 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 uma programação para que o relatório seja entregue. Para consultas do sistema que fornecemos, a API Criar Relatório também pode ser chamada com QueryId.
URL de callback
A API de criação de relatório aceita uma URL de retorno de chamada. Essa URL será chamada assim que a geração do relatório for bem-sucedida. O URL de retorno de chamada deve ser acessível publicamente. Além do URL, um método de retorno de chamada também pode ser fornecido. O método de retorno de chamada só pode ser GET
ou POST
. O método padrão, se nenhum valor for passado, será POST
. O reportId que concluiu a geração sempre será passado de volta durante o retorno de chamada.
Retorno de chamada POST: Se o URL passado for https://www.contosso.com/callback
, o URL de retorno será https://www.contosso.com/callback/<reportID>
Retorno de chamada GET: Se o URL passado for https://www.contosso.com/callback
, o URL de retorno será https://www.contosso.com/callback?reportId=<reportID>
Relatórios ExecuteNow
Há uma disposição para gerar um relatório sem agendamento. A carga útil da API de criação de relatório pode aceitar um parâmetro ExecuteNow
, que enfileirará o relatório a ser gerado assim que a API for chamada. Quando ExecuteNow
é definido como true, os campos: StartTime
, RecurrenceCount
, RecurrenceInterval
são ignorados, pois esses relatórios não estão agendados.
Dois campos adicionais podem ser passados QueryStartTime
quando ExecuteNow
for verdadeiro e QueryEndTime
. Esses dois campos substituirão o TIMESPAN
campo na consulta. Esses campos não são aplicáveis a relatórios programados, pois os dados serão gerados continuamente por um período fixo que não muda.
Sintaxe da solicitação
Método | URI de solicitação |
---|---|
PUBLICAR | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport |
Cabeçalho da solicitação
Cabeçalho | Tipo | Descrição |
---|---|---|
Autorização | corda | Obrigatório O token de acesso do Microsoft Entra. O formato é Bearer <token> . |
Tipo de conteúdo | corda | Application/JSON |
Parâmetro de caminho
Nenhum
Parâmetro de Consulta
Nenhum
Exemplo de conteúdo de solicitação
{
"ReportName": "Top10_CustomersReport",
"Description": "Top 10 customers by revenue for last month",
"QueryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"StartTime": "2021-03-31T18:41:00Z",
"ExecuteNow": false,
"QueryStartTime": null,
"QueryEndTime": null,
"RecurrenceInterval": 24,
"RecurrenceCount": 100,
"Format": "CSV",
"CallbackUrl": "https://<SampleCallbackUrl>",
"CallbackMethod": "GET"
}
Glossário
As principais definições de elementos na carga útil da solicitação são articuladas abaixo:
Parâmetro | Obrigatório | Descrição | Valores permitidos |
---|---|---|---|
Nome do Relatório | Sim | Nome a ser atribuído ao relatório | corda |
Descrição | Não | Descrição do relatório criado | corda |
QueryId | Sim | ID da consulta do relatório | corda |
HoraDeInício | 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 |
corda |
Executar Agora | Não | Esse parâmetro deve ser usado para criar um relatório que será executado apenas uma vez.
StartTime , RecurrenceInterval e RecurrenceCount serão ignorados se estiver definido como true. O relatório é executado imediatamente de forma assíncrona |
verdadeiro/falso |
[QueryStartTime] | Não | Opcionalmente, especifica a hora de início da consulta que extrai os dados. Esse parâmetro é aplicável somente para relatórios de execução única que foram ExecuteNow definidos como true. A configuração desse parâmetro substitui as TIMESPAN indicações na consulta. O formato deve ser aaaa-MM-ddTHH:mm:ssZ |
Timestamp como string |
HoraDeTérminoDaConsulta | Não | Opcionalmente, especifica a hora de término da consulta que extrai os dados. Esse parâmetro é aplicável somente para um relatório de execução de tempo definido ExecuteNow como true. A configuração desse parâmetro substitui as TIMESPAN indicações na consulta. O formato deve ser aaaa-MM-ddTHH:mm:ssZ |
Timestamp como string |
RecurrenceInterval | Sim | Frequência em horas em que o relatório deve ser gerado. O valor mínimo é 4 e o valor máximo é 2160. |
número inteiro |
Contagem de recorrência | Não | Número de relatórios a serem gerados. | número inteiro |
Formato | Não | Formato de arquivo do arquivo exportado. O padrão é CSV. |
"CSV"/"TSV" |
CallbackUrl | Não | URL acessível publicamente que pode ser configurada opcionalmente como destino de retorno de chamada | Cadeia de caracteres (URL http) |
Método de retorno de chamada | Não | O método a ser usado para retorno de chamada | OBTER/POSTAR |
Resposta de exemplo
O conteúdo da resposta é estruturado da seguinte maneira:
Códigos de resposta: 200, 400, 401, 403, 404, 500
Exemplo de conteúdo da resposta:
{
"value": [
{
"reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
"reportName": "Top10_CustomersReport",
"description": "Top 10 customers by revenue for last month",
"queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
"user": "GAUser@PITEST2.onmicrosoft.com",
"createdTime": "2021-03-30T13:11:58Z",
"modifiedTime": null,
"executeNow": false,
"startTime": "2021-03-31T18:41:00Z",
"reportStatus": "Active",
"recurrenceInterval": 24,
"recurrenceCount": 100,
"callbackUrl": "https://<SampleCallbackUrl>",
"callbackMethod": "GET",
"format": "csv"
}
],
"nextLink": null,
"totalCount": 1,
"message": "Report created successfully",
"statusCode": 200,
"dataRedacted": false
}
Glossário
As principais definições de elementos na resposta são articuladas abaixo:
Parâmetro | Descrição |
---|---|
ReportId | UUID (identificador universalmente exclusivo) do relatório que você criou |
Nome do Relatório | Nome fornecido ao relatório no conteúdo da solicitação |
Descrição | Descrição fornecida durante a criação do relatório |
QueryId | ID da consulta transmitida no momento em que você criou o relatório |
Consulta | Texto de consulta que será executado para este relatório |
Utilizador | ID do 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 | UTC Hora em que o relatório foi modificado pela última vez neste formato: aaaa-MM-ddTHH:mm:ssZ |
Executar Agora |
ExecuteNow sinalizador definido no momento em que o relatório foi criado |
HoraDeInício | Hora UTC em que a execução do relatório começará neste formato: aaaa-MM-ddTHH:mm:ssZ |
Status do relatório | Status da execução do relatório. Os valores possíveis são Paused , Active e Inactive |
RecurrenceInterval | Intervalo de recorrência fornecido durante a criação do relatório |
Contagem de recorrência | Contagem de recorrência fornecida durante a criação do relatório. |
CallbackUrl | URL de retorno de chamada fornecida na solicitação |
Método de retorno de chamada | Método de retorno de chamada fornecido na solicitação |
Formato | Formato dos arquivos de relatório. Os valores possíveis são CSV ou TSV . |
ContagemTotal | Número de registros na matriz Value |
CódigoDeStatus | Código de resultado |
mensagem | Os valores possíveis são 200, 400, 401, 403, 500. Mensagem de status da execução da API |
Obter API de execução 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 Create Report. 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 retornará o status. Você também pode usar essa API para obter todas as execuções que aconteceram 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. As execuções pendentes podem ser obtidas definindo executionStatus=Pending
.
Sintaxe da solicitação
Método | URI de solicitação |
---|---|
OBTER | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution} |
Cabeçalho da solicitação
Cabeçalho | Tipo | Descrição |
---|---|---|
Autorização | corda | Obrigatório O token de acesso do Microsoft Entra. O formato é Bearer <token> . |
Tipo de conteúdo | corda | Application/JSON |
Parâmetro de caminho
Nome do parâmetro | Obrigatório | Tipo | Descrição |
---|---|---|---|
reportId | Sim | corda | Filtre para obter detalhes de execução apenas de relatórios com o reportId fornecido neste argumento. Vários reportIds podem ser especificados separando-os com um ponto-e-vírgula ";" |
Parâmetro de consulta
Nome do parâmetro | Obrigatório | Tipo | Descrição |
---|---|---|---|
ID de execução | Não | corda | Filtre para obter detalhes apenas de relatórios com o executionId fornecido neste argumento. Vários executionIds podem ser especificados separando-os com um ponto-e-vírgula ";". |
status de execução | Não | Cadeia de caracteres/enumeração | Filtre para obter detalhes apenas de relatórios com o executionStatus fornecido neste argumento. Os valores válidos são: Pending , Running , Paused , e Completed . O valor padrão é Completed . Vários status podem ser especificados separando-os com um ponto-e-vírgula ";". |
getLatestExecution | Não | booleano | A API retornará detalhes da execução 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. |
Exemplo de conteúdo de solicitação
Nenhum
Resposta de exemplo
O conteúdo da resposta é estruturado da seguinte maneira:
Códigos de resposta: 200, 400, 401, 403, 404, 500
Exemplo de conteúdo da resposta:
{
"value": [
{
"executionId": "906931dc-4f2f-4195-bbb2-d7295c7550d3",
"reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
"recurrenceInterval": 24,
"recurrenceCount": 100,
"callbackUrl": null,
"callbackMethod": null,
"format": "csv",
"executionStatus": "Completed",
"reportLocation": null,
"reportAccessSecureLink": "https://<path to report for download>",
"reportExpiryTime": null,
"reportGeneratedTime": "2021-03-31T18:41:00Z"
}
],
"nextLink": null,
"totalCount": 1,
"message": null,
"statusCode": 200,
"dataRedacted": false
}
Quando a execução do relatório for concluída, o status Completed
da execução será mostrado. Você pode baixar o relatório selecionando a URL no reportAccessSecureLink
.
Glossário
Definições-chave de elementos na resposta.
Parâmetro | Descrição |
---|---|
Identificação da execução | Identificador universalmente exclusivo (UUID) 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 |
Contagem de recorrência | Contagem de recorrência fornecida durante a criação do relatório |
CallbackUrl | URL de retorno de chamada associada à instância de execução |
Método de retorno de chamada | Método de retorno de chamada associado à instância de execução |
Formato | Formato do arquivo gerado no final da execução |
Status de execução | Status da instância de execução do relatório. Os valores válidos são: Pending , Running , Paused , e Completed |
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 |
ContagemTotal | Número de conjuntos de dados na matriz Value |
CódigoDeStatus | Código de resultado Os valores possíveis são 200, 400, 401, 403, 404 e 500 |
mensagem | Mensagem de status da execução da API |
Experimente as APIs por meio do URL da API do swagger