Paradigma de acesso programático - API de aplicativos e jogos

Artigo
06/14/2024

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.

Sintaxe da solicitação

Método	URI da solicitação
POSTAR	`https://manage.devcenter.microsoft.com/consumer/insights/v1.1/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": "PurchaseQuery",
    "Description": "Fetch Purchase related dataset",
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily"
}

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 nas necessidades 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": " PurchaseQuery ",
            "description": " Fetch Purchase related dataset",
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily",
            "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
POSTAR	`https://manage.devcenter.microsoft.com/consumer/insights/v1.1/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

{ 
    "Name": "PurchaseQuery", 
    "Description": "Fetch Purchase related dataset", 
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily" 
}

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 quando definidos 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 um relatório de execução de tempo definido `ExecuteNow` 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''

Payload de resposta

{ 
  "Value": [ 
    { 
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003", 
            "reportName": " PurchaseQuery ", 
            "description": " Fetch Purchase related dataset" 
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "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 só é aplicável 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 só é aplicável 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 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 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://manage.devcenter.microsoft.com/consumer/insights/v1.1/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	aplicativo/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.
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`, `Failed`e `Completed`. O valor padrão é `Completed`.
getLatestExecution	Não	boolean	A API retorna 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.

Payload da 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 payload 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 for concluída, o status de execução será exibido como Completed. É 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`, `Failed` 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 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 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

Compartilhar via

Paradigma de acesso programático - API de aplicativos e jogos

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

Criar API Criar relatório

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro de caminho

Parâmetro de consulta

Exemplo de carga de solicitação

Glossário

Resposta de exemplo

Glossário

Criar API de relatório

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro de caminho

Parâmetro de consulta

Exemplo de carga de solicitação

Glossário

Resposta de exemplo

Payload de resposta

Glossário

Obter API de execuções de relatório

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetro de caminho

Parâmetro de consulta

Payload da solicitação

Resposta de exemplo

Exemplo de payload de resposta

Glossário

Comentários

Recursos adicionais