Compartilhar via


Paradigma do acesso programático

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.

Fluxo de alto nível 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 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.
  2. Em caso de êxito, a API Criar Consulta de Relatório retorna o QueryId.
  3. 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.
  4. Em caso de êxito, a API Criar Relatório retorna o ReportId.
  5. O aplicativo cliente é notificado na URL de retorno de chamada assim que os dados do relatório estão 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 a ID do Relatório e o intervalo de datas.
  7. 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, RecurrenceIntervale 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, Activee 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