Paradigma de acceso mediante programación para marketplace comercial

Artículo
06/14/2024

En este diagrama se muestra el patrón de llamada de API que se usa 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 API

En esta lista se proporcionan más detalles sobre la figura 1.

La aplicación cliente puede definir el esquema o plantilla del informe personalizado llamando a la API de creación de consultas de informes. Como alternativa, puede usar una plantilla de informe (QueryId) de la lista de consultas del sistema.
Si se ejecuta correctamente, la API de creación de plantillas de informes devuelve el elemento QueryId.
A continuación, la aplicación cliente llama a la API de creación de informes con el elemento 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.
Si se ejecuta correctamente, la API de creación de informes devuelve el elemento ReportID.
La aplicación cliente recibe una notificación en el URI de devolución de llamada en cuanto los datos del informe están listos para su descarga.
A continuación, la aplicación cliente usa la API de obtención de ejecuciones de informes para consultar el estado del informe con el Report ID y el intervalo de fechas.
Si se ejecuta correctamente, se devuelve el vínculo de descarga del informe y la aplicación puede iniciar la descarga de los datos.

Especificación del lenguaje de consulta de informes

Aunque proporcionamos consultas del sistema que puede usar para crear informes, también puede crear sus propias consultas en función de sus necesidades empresariales. Para obtener más información sobre las consultas personalizadas, consulte Especificación de consultas personalizadas.

API de creación de consultas de informes

Esta API ayuda a crear consultas personalizadas que definen el conjunto de datos del que deben exportarse las columnas y métricas. La API proporciona la flexibilidad para crear una nueva plantilla de informes en función de sus necesidades empresariales.

También puede usar las consultas del sistema que proporcionamos. Cuando no se necesitan plantillas de informe personalizadas, puede llamar directamente a Create Report API mediante queryIds de las consultas del sistema que proporcionamos.

En el ejemplo siguiente se muestra cómo crear una consulta personalizada para obtener el uso normalizado y los cargos financieros estimados de las SKU de pago del conjunto de datos ISVUsage del último mes.

Sintaxis de la solicitud

Método	URI de solicitud
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

Encabezado de solicitud

Encabezado	Tipo	Descripción
Autorización	string	Necesario. Token de acceso de Microsoft Entra. El formato es `Bearer <token>`.
Content-Type	`string`	`application/JSON`

Parámetro de ruta de acceso

None

Parámetro de consulta

None

Ejemplo de solicitud de carga

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

Glosario

En esta tabla se proporcionan las definiciones clave de los elementos de la carga de solicitud.

Parámetro	Obligatorio	Descripción	Valores permitidos
`Name`	Sí	Nombre descriptivo de la consulta	string
`Description`	No	Descripción de la consulta creada	string
`Query`	Sí	Cadena de consulta basada en la necesidad empresarial	string

Nota:

Para ver ejemplos de consultas personalizadas, consulte consultas de ejemplo.

Respuesta de muestra

La carga de respuesta tiene la estructura siguiente:

Códigos de respuesta: 200, 400, 401, 403, 500

Ejemplo de carga de respuesta:

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

Glosario

En esta tabla se proporcionan las definiciones clave de los elementos de la respuesta.

Parámetro	Descripción
`QueryId`	Identificador único universal (UUID) de la consulta creada
`Name`	Nombre proporcionado en la carga de la solicitud durante la creación de consultas
`Description`	Descripción proporcionada en la carga de la solicitud durante la creación de consultas
`Query`	Consulta de informe personalizada proporcionada en la carga de la solicitud durante la creación de consultas
`Type`	Establézcalo `userDefined` en para consultas creadas manualmente
`User`	Id. de usuario usado para crear la consulta
`CreatedTime`	Hora UTC en la que se creó la consulta. Formato: aaaa-MM-ddTHH:mm:ssZ
`TotalCount`	Número de registros de la matriz Value.
`StatusCode`	Código de resultado Los valores posibles son 200, 400, 401, 403 y 500.
`message`	Mensaje de estado de la ejecución de la API.

API de creación de informes

Al crear una plantilla de informe personalizada correctamente y recibir el elemento QueryID como parte de la respuesta de Creación de consultas de informes, se puede llamar a esta API para programar la ejecución de una consulta a intervalos regulares. Puede establecer una frecuencia y una programación para la entrega del informe. En el caso de las consultas del sistema que proporcionamos, también se puede llamar a la API de creación de informes con QueryId.

Sintaxis de la solicitud

Método	URI de solicitud
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

Encabezado de solicitud

Encabezado	Tipo	Descripción
Autorización	string	Necesario. Token de acceso de Microsoft Entra. El formato es `Bearer <token>`.
Tipo de contenido	string	`application/JSON`

Parámetro de ruta de acceso

None

Parámetro de consulta

None

Ejemplo de solicitud de carga

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

Glosario

En esta tabla se proporcionan las definiciones clave de los elementos de la carga de solicitud.

Parámetro	Obligatorio	Descripción	Valores permitidos
`ReportName`	Sí	Nombre descriptivo asignado al informe	Cadena
`Description`	No	Descripción del informe creado	Cadena
`QueryId`	Sí	Identificador de consulta que se debe usar para la generación de informes	Cadena
`StartTime`	Sí	Marca de tiempo UTC en la que comenzará la generación del informe. El formato debe ser aaaa-MM-ddTHH:mm:ssZ.	Cadena
`ExecuteNow`	No	Este parámetro se debe usar para crear un informe que se ejecute solo una vez. `StartTime`, `RecurrenceInterval`, `RecurrenceCount`y `EndTime` se omiten si se establece en . `true`	Booleano
`QueryStartTime`	No	Opcionalmente, especifica la hora de inicio de la consulta que extrae los datos. Este parámetro solo es aplicable a un informe de una sola ejecución que tiene `ExecuteNow` establecido en `true`. El formato debe ser aaaa-MM-ddTHH:mm:ssZ.	Marca de tiempo como string
`QueryEndTime`	No	Opcionalmente, especifica la hora de fin de la consulta que extrae los datos. Este parámetro solo es aplicable a un informe de una sola ejecución que tiene `ExecuteNow` establecido en `true`. El formato debe ser aaaa-MM-ddTHH:mm:ssZ.	Marca de tiempo como string
`RecurrenceInterval`	Sí	Frecuencia en horas en que se debe generar el informe. El valor mínimo es 1 y el valor máximo es 17520	Entero
`RecurrenceCount`	Sí	Número de informes que se van a generar. El límite depende del intervalo de periodicidad.	Entero
`Format`	No	Formato del archivo exportado. El formato predeterminado es CSV	CSV/TSV
`CallbackUrl`	No	Dirección URL accesible públicamente que se puede configurar opcionalmente como destino de devolución de llamada	Cadena
`CallbackMethod`	No	Método Get/Post que se puede configurar con la dirección URL de devolución de llamada	GET/POST
`EndTime`	Sí	Marca de tiempo UTC en la que finalizará la generación de informes. El formato debe ser aaaa-MM-ddTHH:mm:ssZ.	Cadena

Nota:

Al crear el informe, ya sea EndTime o combinación de RecurrenceInterval y RecurrenceCount es obligatorio.

Respuesta de muestra

La carga de respuesta tiene la estructura siguiente:

Código de respuesta: 200, 400, 401, 403, 404, 500.

Carga de respuesta:

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "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
}

Glosario

En esta tabla se proporcionan las definiciones clave de los elementos de la respuesta.

Parámetro	Descripción
`ReportId`	Identificador único universal (UUID) del informe que creó.
`ReportName`	Nombre proporcionado en la carga de solicitud durante la creación del informe
`Description`	Descripción proporcionada en la carga de solicitud durante la creación del informe
`QueryId`	Identificador de consulta proporcionado en la carga de la solicitud durante la creación del informe
`Query`	Texto de la consulta que se ejecutará para este informe
`User`	Id. de usuario usado para crear el informe.
`CreatedTime`	Hora UTC en que se creó el informe en el formato aaaa-MM-ddTHH:mm:ssZ.
`ModifiedTime`	Hora UTC en que se modificó el informe en el formato aaaa-MM-ddTHH:mm:ssZ.
`ExecuteNow`	Parámetro ExecuteNow proporcionado en la carga de solicitud durante la creación del informe
`queryStartTime`	Hora de inicio de la consulta proporcionada en la carga de la solicitud durante la creación del informe. Esto solo es aplicable si `ExecuteNow` se establece en "True"
`queryEndTime`	Hora de finalización de la consulta proporcionada en la carga de la solicitud durante la creación del informe. Esto solo es aplicable si `ExecuteNow` se establece en "True"
`StartTime`	Hora de inicio proporcionada en la carga de la solicitud durante la creación del informe
`ReportStatus`	Estado de la ejecución del informe. Los valores posibles son En pausa, Activo e Inactivo.
`RecurrenceInterval`	Intervalo de periodicidad proporcionado en la carga de la solicitud durante la creación del informe
`RecurrenceCount`	Recuento de periodicidad restante para el informe
`CallbackUrl`	Dirección URL de devolución de llamada proporcionada en la carga de la solicitud durante la creación del informe
`CallbackMethod`	Método de devolución de llamada proporcionado en la carga de la solicitud durante la creación del informe
`Format`	Formato de los archivos de informe proporcionados en la carga de solicitud durante la creación del informe
`EndTime`	Hora de finalización proporcionada en la carga de la solicitud durante la creación del informe. Esto solo es aplicable si `ExecuteNow` se establece en "True"
`TotalRecurrenceCount`	`RecurrenceCount` proporcionado en la carga de solicitud durante la creación del informe
`nextExecutionStartTime`	Marca de tiempo UTC cuando se inicie la próxima ejecución del informe
`TotalCount`	Número de registros de la matriz Value.
`StatusCode`	Código de resultado. Los valores posibles son 200, 400, 401, 403 y 500.
`message`	Mensaje de estado de la ejecución de la API.

API de obtención de ejecuciones de informes

Puede usar este método para consultar el estado de la ejecución de un informe con el elemento ReportId recibido de la API de creación de informes. 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 devolverá el estado. También puede usar 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 devolverá 404. Las ejecuciones pendientes se pueden obtener estableciendo executionStatus=Pending.

Sintaxis de la solicitud

Método	URI de solicitud
Obtener	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Encabezado de solicitud

Encabezado	Tipo	Descripción
Autorización	string	Necesario. Token de acceso de Microsoft Entra. El formato es `Bearer <token>`.
Tipo de contenido	string	`application/json`

Parámetro de ruta de acceso

None

Parámetro de consulta

Nombre de parámetro	Obligatorio	Type	Descripción
`reportId`	Sí	string	Filtrar para obtener los detalles de ejecución solo de los informes con el elemento `reportId` especificado en este argumento.
`executionId`	No	string	Filtrar para obtener los detalles de solo los informes con el elemento `executionId` especificado en este argumento. Se pueden especificar varios `executionIds` separandolos con un punto y coma ";".
`executionStatus`	No	string/enum	Filtrar para obtener los detalles de solo los informes con el elemento `executionStatus` especificado en este argumento. Los valores válidos son `Pending`, `Running`, `Paused` y `Completed`. El valor predeterminado es `Completed`.
`getLatestExecution`	No	boolean	La API devolverá los detalles de la ejecución más reciente del informe. De manera predeterminada, este parámetro está establecido en `true`. Si opta por pasar el valor de este parámetro como `false`, la API devolverá las instancias de ejecución de los últimos 90 días.

Carga de solicitud

None

Respuesta de muestra

La carga de respuesta tiene la estructura siguiente:

Códigos de respuesta: 200, 400, 401, 403, 404, 500

Ejemplo de carga de respuesta:

{
    "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
}

Una vez completada la ejecución del informe, se muestra el estado de ejecución Completed. Puede descargar el informe seleccionando la dirección URL en reportAccessSecureLink.

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`	Dirección URL de devolución de llamada asociada a la instancia de ejecución.
`CallbackMethod`	Método de devolución de llamada proporcionado en la carga de la solicitud durante la creación del informe
`Format`	Formato del archivo generado al final de la ejecución.
`ExecutionStatus`	Estado de la instancia de ejecución del informe. Los valores válidos son `Pending`, `Running`, `Paused` y `Completed`.
`ReportLocation`	Ubicación donde se descarga el informe.
`ReportAccessSecureLink`	Vínculo a través del cual se puede acceder al informe de forma segura.
`ReportExpiryTime`	Hora UTC después de la cual el vínculo de informe expirará en el formato aaaa-MM-ddTHH:mm:ssZ.
`ReportGeneratedTime`	Hora UTC a la que se generó el informe en el formato aaaa-MM-ddTHH:mm:ssZ.
`EndTime`	Hora de finalización proporcionada en la carga de la solicitud durante la creación del informe. Esto solo es aplicable si `ExecuteNow` se establece en "True"
`TotalRecurrenceCount`	`RecurrenceCount` proporcionado en la carga de solicitud durante la creación del informe
`nextExecutionStartTime`	Marca de tiempo UTC cuando se inicie la próxima ejecución del informe
`TotalCount`	Número de conjuntos de datos en la matriz de valores.
`StatusCode`	Código de resultado Los valores posibles son 200, 400, 401, 403, 404 y 500.
`message`	Mensaje de estado de la ejecución de la API.

Pasos siguientes

Puede probar las API a través de la dirección URL de la API de Swagger.
Realice la primera llamada API para los informes de Marketplace Insights.

Compartir a través de

Paradigma de acceso mediante programación para marketplace comercial

Especificación del lenguaje de consulta de informes

API de creación de consultas de informes

API de creación de informes

API de obtención de ejecuciones de informes

Pasos siguientes

Comentarios

Comentarios

Recursos adicionales