Compartir a través de

Paradigma del acceso mediante programación

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.

Flujo de alto nivel Figura 1: Flujo de alto nivel del patrón de llamada a la API

Esta lista proporciona más detalles sobre la Figura 1.

  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.
  2. En caso de éxito, la API Create Report Query devuelve QueryId.
  3. 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.
  4. En caso de éxito, la API Create Report devuelve el ReportId.
  5. 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.
  6. 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.
  7. 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, RecurrenceIntervaly 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, Activey 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 reportAccessSecureLinkarchivo .

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, Pausedy 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

Contenido relacionado