Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En este diagrama se muestra el patrón de llamada a la API utilizado para crear una nueva plantilla de informe, programar el informe personalizado y recuperar los datos de error.
Figura 1: Flujo de alto nivel del patrón de llamada a la API
Esta lista proporciona más detalles sobre la Figura 1.
- La aplicación cliente puede definir el esquema o la plantilla de informe personalizado llamando a la API Crear consulta de informe. Como alternativa, puede elegir una plantilla de informe (QueryId) de los ejemplos de biblioteca de plantillas de informe en Lista de consultas del sistema para el acceso mediante programación de información de asociados.
- En caso de éxito, la API Create Report Query devuelve QueryId.
- A continuación, la aplicación cliente debe llamar a la API Create Report mediante QueryId junto con la fecha de inicio del informe, el intervalo de repetición, la periodicidad y un URI de devolución de llamada opcional.
- En caso de éxito, la API Create Report devuelve el ReportId.
- La aplicación cliente recibe una notificación en la dirección URL de devolución de llamada tan pronto como los datos del informe están listos para su descarga.
- A continuación, la aplicación cliente usa la API Obtener ejecuciones de informes para consultar el estado del informe con el identificador de informe y el intervalo de fechas.
- Si se realiza correctamente, se devuelve el enlace de descarga del informe y la aplicación puede iniciar la descarga de los datos.
Especificación del lenguaje de consulta de informes
Si bien proporcionamos consultas del sistema que puede usar para crear informes, también puede crear sus propias consultas en función de las necesidades de su negocio. Para obtener más información sobre las consultas personalizadas, consulte Especificación de consultas personalizadas.
Creación de una API de consulta de informes
La API ayuda a crear consultas personalizadas que definen el conjunto de datos desde el que se deben exportar las columnas y las métricas. La API proporciona la flexibilidad necesaria para crear una nueva plantilla de informes en función de las necesidades de su empresa.
También puede utilizar las consultas del sistema que proporcionamos. Cuando no se necesitan plantillas de informe personalizadas, puede llamar directamente a la API Create Report mediante los QueryIds de las consultas del sistema que se proporcionan.
En el ejemplo siguiente se muestra cómo crear una consulta personalizada para obtener los 10 clientes principales por ingresos del mes pasado.
Sintaxis de la solicitud
Método | Solicitud de URI |
---|---|
EXPONER | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries |
Cabecera de solicitud
Cabecera | Tipo | Descripción |
---|---|---|
Autorización | cuerda / cadena | Obligatorio. El token de acceso de Microsoft Entra. El formato es Bearer <token> . |
Tipo de contenido | cuerda / cadena | Application/JSON |
Parámetro path
Ninguno
Parámetro de consulta
Ninguno
Carga útil de solicitud de muestra
{
"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"
}
Glosario de solicitudes
Esta tabla proporciona las definiciones de clave de los elementos en la carga útil de la solicitud.
Parámetro | Obligatorio | Descripción | Valores permitidos |
---|---|---|---|
Nombre | Sí | Nombre descriptivo de la consulta | cuerda / cadena |
Descripción | No | Descripción de lo que devuelve la consulta | cuerda / cadena |
Consulta | Sí | Cadena de consulta de informe | Tipo de datos: string Consulta personalizada basada en las necesidades del negocio |
Nota:
Para ver ejemplos de consultas personalizadas, consulte Ejemplos de consultas de ejemplo.
Respuesta de ejemplo
La carga de respuesta se estructura de la manera siguiente:
Códigos de respuesta: 200, 400, 401, 403, 500
Ejemplo de carga de respuesta:
{
"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
}
Glosario de respuesta
Esta tabla proporciona las definiciones de clave de los elementos en la carga útil de la solicitud.
Parámetro | Descripción |
---|---|
QueryId | Identificador único universal (UUID) de la consulta que ha creado |
Nombre | Nombre descriptivo dado a la consulta en la carga útil de la solicitud |
Descripción | Descripción dada durante la creación de la consulta |
Consulta | Consulta de informe pasada como entrada durante la creación de la consulta |
Tipo | Configurar userDefined |
Usuario | ID de usuario utilizado para crear la consulta |
CreatedTime | Hora UTC en que se creó la consulta en este formato: aaaa-MM-ddTHH:mm:ssZ |
Conteo Total | Número de conjuntos de datos de la matriz Value |
Código de estado | Código de resultado Los valores posibles son 200, 400, 401, 403, 500 |
Mensaje | Mensaje de estado de la ejecución de la API |
Crear API de informes
Al crear correctamente una plantilla de informe personalizada y recibir el QueryID como parte de la respuesta Crear consulta de informe , se puede llamar a esta API para programar una consulta para que se ejecute a intervalos regulares. Puede establecer una frecuencia y una programación para que se entregue el informe. En el caso de las consultas del sistema que proporcionamos, también se puede llamar a la API Crear informe con QueryId.
URL de callback
La API de creación de informes acepta una URL de devolución de llamada. Se llamará a esta URL una vez que la generación del informe se haya realizado correctamente. La URL de devolución de llamada debe ser accesible públicamente. Además de la URL, también se puede proporcionar un método de devolución de llamada. El método de devolución de llamada solo puede ser GET
o POST
. El método predeterminado si no se pasa ningún valor será POST
. El reportId que ha completado la generación siempre se devolverá durante la devolución de llamada.
Devolución de llamada POST: Si la URL pasada fue https://www.contosso.com/callback
, entonces la URL de devolución llamada será https://www.contosso.com/callback/<reportID>
Devolución de llamada GET: Si la URL pasada fue https://www.contosso.com/callback
, entonces la URL de devolución llamada será https://www.contosso.com/callback?reportId=<reportID>
Informes de ExecuteNow
Existe una disposición para generar un informe sin programación. La carga útil de la API de creación de informes puede aceptar un parámetro ExecuteNow
, que pondrá en cola el informe que se generará tan pronto como se llame a la API. Cuando ExecuteNow
se establece en true, los campos: StartTime
, RecurrenceCount
, RecurrenceInterval
se omiten ya que estos informes no están programados.
Se pueden pasar dos campos adicionales cuando ExecuteNow
es verdadero, QueryStartTime
y QueryEndTime
. Estos dos campos invalidarán el TIMESPAN
campo de la consulta. Estos campos no son aplicables a los informes programados, ya que los datos se generarán continuamente durante un período de tiempo fijo que no cambia.
Sintaxis de la solicitud
Método | Solicitud de URI |
---|---|
EXPONER | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport |
Cabecera de solicitud
Cabecera | Tipo | Descripción |
---|---|---|
Autorización | cuerda / cadena | Obligatorio. El token de acceso de Microsoft Entra. El formato es Bearer <token> . |
Tipo de contenido | cuerda / cadena | Application/JSON |
Parámetro de ruta
Ninguno
Parámetro de consulta
Ninguno
Carga útil de solicitud de muestra
{
"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"
}
Glosario
A continuación se articulan las definiciones clave de los elementos de la carga útil de la solicitud:
Parámetro | Obligatorio | Descripción | Valores permitidos |
---|---|---|---|
NombreDelInforme | Sí | Nombre que se va a asignar al informe | cuerda / cadena |
Descripción | No | Descripción del informe creado | cuerda / cadena |
QueryId | Sí | Id. de consulta de informe | cuerda / cadena |
HoraDeInicio | Sí | Marca de tiempo UTC en la que comenzará la generación del informe. El formato debe ser: aaaa-MM-ddTHH:mm:ssZ |
cuerda / cadena |
Ejecutar ahora | No | Este parámetro se debe usar para crear un informe que se ejecutará solo una vez.
StartTime , RecurrenceInterval y RecurrenceCount se omiten si se establece en true. El informe se ejecuta inmediatamente de forma asincrónica |
verdadero/falso |
HoraDeInicioDeConsulta | No | Opcionalmente, especifica la hora de inicio de la consulta que extrae los datos. Este parámetro solo se aplica a los informes de ejecución única que se han ExecuteNow establecido en true. Al establecer este parámetro, se invalidan los TIMESPAN datos proporcionados en la consulta. El formato debe ser aaaa-MM-ddTHH:mm:ssZ |
Marca de tiempo como cadena |
QueryEndTime | No | Opcionalmente, especifica la hora de finalización de la consulta que extrae los datos. Este parámetro solo es aplicable para los informes de ejecución de una sola vez que se han ExecuteNow establecido en true. Al establecer este parámetro, se invalidan los TIMESPAN datos proporcionados en la consulta. El formato debe ser aaaa-MM-ddTHH:mm:ssZ |
Marca de tiempo como cadena |
RecurrenceInterval | Sí | Frecuencia en horas en las que se debe generar el informe. El valor mínimo es 4 y el valor máximo es 2160. |
entero |
RecurrenceCount | No | Número de informes que se van a generar. | entero |
Formato | No | Formato de archivo del archivo exportado. El valor predeterminado es CSV. |
"CSV"/"TSV" |
CallbackUrl | No | URL accesible públicamente que se puede configurar opcionalmente como destino de devolución de llamada | Cadena (URL http) |
CallbackMethod | No | El método que se va a utilizar para la devolución de llamada | OBTENER/PUBLICAR |
Respuesta de ejemplo
La carga de respuesta se estructura de la manera siguiente:
Códigos de respuesta: 200, 400, 401, 403, 404, 500
Ejemplo de carga de respuesta:
{
"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
}
Glosario
A continuación se exponen las definiciones clave de los elementos de la respuesta:
Parámetro | Descripción |
---|---|
ReportId | Identificador único universal (UUID) del informe que ha creado |
NombreDelInforme | Nombre proporcionado al informe en la carga de la solicitud |
Descripción | Descripción dada durante la creación del informe |
QueryId | Id. de consulta pasado en el momento de crear el informe |
Consulta | Texto de consulta que se ejecutará para este informe |
Usuario | Identificador de usuario usado para crear el informe |
CreatedTime | Hora UTC en que se creó el informe en este formato: aaaa-MM-ddTHH:mm:ssZ |
ModifiedTime | Hora UTC en que se modificó por última vez el informe en este formato: aaaa-MM-ddTHH:mm:ssZ |
Ejecutar ahora |
ExecuteNow Marca establecida en el momento en que se creó el informe |
HoraDeInicio | Hora UTC en que comenzará la ejecución del informe en este formato: aaaa-MM-ddTHH:mm:ssZ |
ReportStatus | Estado de la ejecución del informe. Los valores posibles son Paused , Active y Inactive |
RecurrenceInterval | Intervalo de periodicidad proporcionado durante la creación del informe |
RecurrenceCount | Recuento de periodicidad proporcionado durante la creación del informe. |
CallbackUrl | Dirección URL de devolución de llamada proporcionada en la solicitud |
CallbackMethod | Método de devolución de llamada proporcionado en la solicitud |
Formato | Formato de los archivos de informe. Los valores posibles son CSV o TSV . |
Conteo Total | Número de registros en la matriz Value |
Código de estado | Código de resultado |
Mensaje | Los valores posibles son 200, 400, 401, 403, 500. Mensaje de estado de la ejecución de la API |
Obtener la API de ejecución de informes
Puede usar este método para consultar el estado de la ejecución de un informe mediante el ReportId recibido de la API Create Report. El método devuelve el vínculo de descarga del informe si el informe está listo para su descarga. De lo contrario, el método devuelve el estado. También puede utilizar esta API para obtener todas las ejecuciones que se han producido para un informe determinado.
Importante
Esta API tiene parámetros de consulta predeterminados establecidos para executionStatus=Completed
y getLatestExecution=true
. Por lo tanto, si se llama a la API antes de la primera ejecución correcta del informe, se devolverá 404. Las ejecuciones pendientes se pueden obtener configurando executionStatus=Pending
.
Sintaxis de la solicitud
Método | Solicitud de URI |
---|---|
OBTENER | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution} |
Cabecera de solicitud
Cabecera | Tipo | Descripción |
---|---|---|
Autorización | cuerda / cadena | Obligatorio. El token de acceso de Microsoft Entra. El formato es Bearer <token> . |
Tipo de contenido | cuerda / cadena | Application/JSON |
Parámetro path
Nombre de parámetro | Obligatorio | Tipo | Descripción |
---|---|---|---|
Id de informe | Sí | cuerda / cadena | Filtre para obtener detalles de ejecución solo de los informes con el reportId proporcionado en este argumento. Se pueden especificar varios reportIds separándolos con un punto y coma ";" |
Parámetro de consulta
Nombre de parámetro | Obligatorio | Tipo | Descripción |
---|---|---|---|
executionId | No | cuerda / cadena | Filtre para obtener detalles solo de los informes con el executionId proporcionado en este argumento. Se pueden especificar varios executionIds separándolos con un punto y coma ";". |
executionStatus | No | Cadena/enumeración | Filtre para obtener detalles solo de los informes con el executionStatus proporcionado en este argumento. Los valores válidos son: Pending , Running , Paused , y Completed . El valor predeterminado es Completed . Se pueden especificar varios estados separándolos con un punto y coma ";". |
getLatestExecution | No | booleano | La API devolverá detalles de la última ejecución. De forma predeterminada, este parámetro se establece en true. Si elige pasar el valor de este parámetro como falso, la API devolverá las instancias de ejecución de los últimos 90 días. |
Carga útil de solicitud de muestra
Ninguno
Respuesta de ejemplo
La carga de respuesta se estructura de la manera siguiente:
Códigos de respuesta: 200, 400, 401, 403, 404, 500
Ejemplo de carga de respuesta:
{
"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
}
Una vez completada la ejecución del informe, se muestra el estado Completed
de ejecución. Para descargar el informe, seleccione la dirección URL en el reportAccessSecureLink
archivo .
Glosario
Definiciones clave de los elementos de la respuesta.
Parámetro | Descripción |
---|---|
ExecutionId | Identificador único universal (UUID) de la instancia de ejecución |
ReportId | ID de informe asociado a la instancia de ejecución |
RecurrenceInterval | Intervalo de periodicidad proporcionado durante la creación del informe |
RecurrenceCount | Recuento de periodicidad proporcionado durante la creación del informe |
CallbackUrl | URL de devolución de llamada asociada a la instancia de ejecución |
CallbackMethod | Método de devolución de llamada asociado a la instancia de ejecución |
Formato | Formato del archivo generado al final de la ejecución |
Estado de ejecución | Estado de la instancia de ejecución del informe. Los valores válidos son: Pending , Running , Paused y Completed |
ReportAccessSecureLink | Enlace a través del cual se puede acceder al informe de forma segura |
ReportExpiryTime | Hora UTC después de la cual el enlace del informe caducará en este formato: aaaa-MM-ddTHH:mm:ssZ |
ReportGeneratedTime | Hora UTC en la que se generó el informe en este formato: aaaa-MM-ddTHH:mm:ssZ |
Conteo Total | Número de conjuntos de datos de la matriz Value |
Código de estado | Código de resultado Los valores posibles son 200, 400, 401, 403, 404 y 500 |
Mensaje | Mensaje de estado de la ejecución de la API |
Pruebe las API a través de la URL de la API de swagger