Paradigma de acceso mediante programación para Microsoft Marketplace

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 llamadas 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 utilizar una plantilla de informe (QueryId) de la lista de consultas del sistema.
2. En caso de éxito, la API Crear plantilla de informe devuelve el archivo QueryId.
3. A continuación, la aplicación cliente llama a la API Crear informe mediante el 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 de creación de informes devuelve el archivo ReportID.
5. La aplicación cliente recibe una notificación en el URI 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 Get Report Executions para consultar el estado del informe con el Report ID intervalo de fechas y.
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

Esta 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 informes personalizadas, puede llamar directamente a la API Crear informe mediante los 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 para SKU de pago del conjunto de datos ISVUsage del último mes.

Sintaxis de la solicitud

Encabezado de solicitud

Parámetro de ruta de acceso

Ninguno

Parámetro de consulta

Ninguno

Ejemplo de carga útil de solicitud

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

Esta tabla proporciona las definiciones de clave de los elementos en la carga útil de la solicitud.

Respuesta de muestra

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": "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

Esta tabla proporciona las definiciones clave de los elementos de la respuesta.

Crear API de informes

Al crear correctamente una plantilla de informe personalizada y recibir la respuesta como parte de Crear QueryIDconsulta 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.

Sintaxis de la solicitud

Encabezado de solicitud

Parámetro de ruta de acceso

Ninguno

Parámetro de consulta

Ninguno

Ejemplo de carga útil de solicitud

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

Esta tabla proporciona las definiciones de clave de los elementos en la carga útil de la solicitud.

Respuesta de muestra

La carga de respuesta se estructura de la manera siguiente:

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

Carga útil 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

Esta tabla proporciona las definiciones clave de los elementos de la respuesta.

Obtener API de ejecuciones de informes

Puede utilizar este método para consultar el estado de la ejecución de un informe mediante el ReportId recibido de la API Crear informe. 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.

Sintaxis de la solicitud

Encabezado de solicitud

Parámetro de ruta de acceso

Ninguno

Parámetro de consulta

Solicitud de carga útil

Ninguno

Respuesta de muestra

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": "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 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.

Puede probar las API a través de la dirección URL de la API de Swagger .

Contenido relacionado

• Realice su primera llamada a la API para los informes de Marketplace Insights