Парадигма программного доступа для коммерческой платформы

На этой схеме показан шаблон вызова API, используемый для создания нового шаблона отчета, планирования пользовательского отчета и получения данных о сбоях.

рис. 1. Высокий уровень потока шаблона вызова API

Этот список содержит дополнительные сведения о рис. 1.

1. Клиентское приложение может определить настраиваемую схему или шаблон отчета, вызвав API создания запросов отчетов. В качестве альтернативы вы можете использовать шаблон отчета (QueryId) из списка системных запросов.
2. При успешном выполнении API для создания шаблона отчета возвращает QueryId.
3. Затем клиентское приложение вызывает API создания отчетов с помощью QueryID вместе с датой начала отчета, интервалом повторения, повторением и необязательным URI обратного вызова.
4. При успешном выполнении API создания отчетов возвращает ReportID.
5. Клиентское приложение получает уведомление по URI обратного вызова, как только данные отчета готовы к загрузке.
6. Затем клиентское приложение использует API выполнения отчетов для запроса состояния отчета с помощью диапазона Report ID и даты.
7. При успешном выполнении возвращается ссылка на скачивание отчета, и приложение может инициировать скачивание данных.

Спецификация языка запросов отчета

Хотя мы предоставляем системные запросы, которые можно использовать для создания отчетов, вы также можете создавать собственные запросы на основе ваших бизнес-потребностей. Дополнительные сведения о пользовательских запросах см. в спецификации пользовательских запросов.

Создание API запросов отчета

Этот API помогает создавать пользовательские запросы, определяющие набор данных, из которого необходимо экспортировать столбцы и метрики. API обеспечивает гибкость создания нового шаблона отчетов на основе бизнес-потребностей.

Вы также можете использовать системные запросы, которые мы предоставляем. Если пользовательские шаблоны отчетов не требуются, можно вызывать API создания отчетов напрямую с помощью queryIds системных запросов.

В следующем примере показано, как создать пользовательский запрос, чтобы получить нормализированное использование и предполагаемые финансовые расходы за платные SKU из набора данных ISVUsage за последний месяц.

синтаксис запроса

Заголовок запроса

параметр path

Никакой

параметр запроса

Никакой

пример полезных данных запроса

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

глоссарий

Эта таблица содержит ключевые определения элементов в полезных данных запроса.

пример ответа

Полезные данные ответа структурированы следующим образом:

Коды отклика: 200, 400, 401, 403, 500

Пример полезных данных ответа:

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

глоссарий

Эта таблица содержит ключевые определения элементов в ответе.

Создание API отчетов

После успешного создания пользовательского шаблона отчета и получения QueryID в ответ на создание запроса отчета , этот API может быть вызван для планирования выполнения запроса с регулярными интервалами. Можно задать частоту и расписание доставки отчета. API создания отчетов для системных запросов можно также вызывать с помощью QueryId.

синтаксис запроса

Заголовок запроса

параметр путь

Никакой

параметр запроса

Никакой

пример полезных данных запроса

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

глоссарий

Эта таблица содержит ключевые определения элементов в нагрузке запроса.

пример ответа

Загрузка данных ответа структурирована следующим образом:

Код ответа: 200, 400, 401, 403, 404, 500

Полезная нагрузка ответа

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

глоссарий

Эта таблица содержит ключевые определения элементов в ответе.

Получение API выполнения отчетов

Этот метод можно использовать для запроса состояния выполнения отчета с помощью ReportId, полученного из API создания отчетов. Метод возвращает ссылку на скачивание отчета, если отчет готов к загрузке. В противном случае метод возвращает состояние. Этот API также можно использовать для получения всех выполнений, которые произошли для данного отчета.

синтаксис запроса

Заголовок запроса

параметр пути

Никакой

параметр запроса

нагрузка запроса

Никакой

пример ответа

Полезные данные ответа структурированы следующим образом:

Коды отклика: 200, 400, 401, 403, 404, 500

Пример полезной нагрузки ответа:

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

После завершения выполнения отчета отображается состояние выполнения Completed. Вы можете скачать отчет, выбрав URL-адрес в reportAccessSecureLink.

глоссарий

Ключевые определения элементов в ответе.

Вы можете протестировать API через URL-адрес Swagger API .

Связанное содержимое

• Создание первого вызова API для отчетов Marketplace Insights