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

Статья
06/14/2024

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

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

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

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

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

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

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

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

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

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

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

Способ	URI запроса
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

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

Верхний колонтитул	Тип	Описание
Авторизация	строка	Обязательный. Маркер доступа Microsoft Entra. Формат — `Bearer <token>`.
Тип контента	`string`	`application/JSON`

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

нет

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

нет

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

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

Словарь терминов

В этой таблице приводятся основные определения элементов в полезных данных запроса.

Параметр	Обязательное поле	Описание	Допустимые значения
`Name`	Да	Понятное имя запроса	строка
`Description`	Нет	Описание созданного запроса	строка
`Query`	Да	Строка запроса на основе бизнес-потребности	строка

Примечание.

Примеры пользовательских запросов см . в примерах запросов.

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

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

Коды отклика: 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
}

Словарь терминов

В этой таблице приводятся основные определения элементов в ответе.

Параметр	Описание
`QueryId`	Универсальный уникальный идентификатор (UUID) созданного запроса
`Name`	Имя, предоставленное в полезных данных запроса во время создания запроса
`Description`	Описание, предоставленное в полезных данных запроса во время создания запроса
`Query`	Настраиваемый запрос отчета, предоставленный в полезных данных запроса во время создания запроса
`Type`	`userDefined` Установка для созданных вручную запросов
`User`	Идентификатор пользователя, используемый для создания запроса
`CreatedTime`	Время UTC при создании запроса. Формат: гггг-ММ-ддTHH:мм:ssZ
`TotalCount`	Число записей в массиве значений
`StatusCode`	Код результата Возможные значения — 200, 400, 401, 403, 500
`message`	Сообщение о состоянии из выполнения API

API создания отчетов

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

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

Способ	URI запроса
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

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

Верхний колонтитул	Тип	Описание
Авторизация	строка	Обязательный. Маркер доступа Microsoft Entra. Формат — `Bearer <token>`.
Тип содержимого	строка	`application/JSON`

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

нет

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

нет

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

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

Словарь терминов

В этой таблице приводятся основные определения элементов в полезных данных запроса.

Параметр	Обязательное поле	Описание	Допустимые значения
`ReportName`	Да	Понятное имя, назначенное отчету	Строка
`Description`	Нет	Описание созданного отчета	Строка
`QueryId`	Да	Идентификатор запроса, который необходимо использовать для создания отчетов	Строка
`StartTime`	Да	Метка времени в формате UTC, после которой начнется создание отчета. Требуемый формат: гггг-мм-ддTчч:мм:ссZ	Строка
`ExecuteNow`	Нет	Этот параметр следует использовать для создания отчета, который выполняется только один раз. `StartTime`, , `RecurrenceIntervalRecurrenceCount`и `EndTime` игнорируются, если задано значение .`true`	Логический
`QueryStartTime`	No	Дополнительно указывает время начала для запроса на извлечение данных. Этот параметр применяется только к разовому отчету о выполнении, для которого параметр `ExecuteNow` имеет значение `true`. Требуемый формат: гггг-мм-ддTчч:мм:ссZ	Отметка времени в виде строки
`QueryEndTime`	No	Дополнительно указывает время окончания для запроса на извлечение данных. Этот параметр применяется только к разовому отчету о выполнении, для которого параметр `ExecuteNow` имеет значение `true`. Требуемый формат: гггг-мм-ддTчч:мм:ссZ	Отметка времени в виде строки
`RecurrenceInterval`	Да	Периодичность создания отчета в часах. Минимальное значение равно 1, а максимальное — 17520	Целое число
`RecurrenceCount`	Да	Число создаваемых отчетов. Ограничение зависит от интервала повторения	Целое число
`Format`	No	Формат экспортируемого файла. Формат по умолчанию — CSV	CSV/TSV
`CallbackUrl`	No	Общедоступный URL-адрес, который можно при необходимости настроить в качестве назначения обратного вызова.	Строка
`CallbackMethod`	Нет	Метод Get/Post, который можно настроить с ПОМОЩЬЮ URL-адреса обратного вызова	GET/POST
`EndTime`	Да	Метка времени в формате UTC, в которой будет завершено создание отчета. Требуемый формат: гггг-мм-ддTчч:мм:ссZ	Строка

Примечание.

При создании отчета EndTime или сочетании RecurrenceInterval и RecurrenceCount является обязательным.

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

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

Код ответа: 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
}

Словарь терминов

В этой таблице приводятся основные определения элементов в ответе.

Параметр	Описание
`ReportId`	Универсальный уникальный идентификатор (UUID) созданного отчета
`ReportName`	Имя, предоставленное в полезных данных запроса во время создания отчета
`Description`	Описание, предоставленное в полезных данных запроса во время создания отчета
`QueryId`	Идентификатор запроса, предоставленный в полезных данных запроса во время создания отчета
`Query`	Текст запроса, который будет выполнен для этого отчета
`User`	Идентификатор пользователя, используемый для создания отчета
`CreatedTime`	Время создания отчета в формате UTC: гггг-мм-ddTчч: мм: ссZ
`ModifiedTime`	Время последнего изменения отчета в формате UTC: гггг-мм-ddTчч: мм: ссZ
`ExecuteNow`	Параметр ExecuteNow, предоставленный в полезных данных запроса во время создания отчета
`queryStartTime`	Время начала запроса, предоставленное в полезных данных запроса во время создания отчета. Это применимо только в том случае, если `ExecuteNow` задано значение True
`queryEndTime`	Время окончания запроса, предоставленное в полезных данных запроса во время создания отчета. Это применимо только в том случае, если `ExecuteNow` задано значение True
`StartTime`	Время начала, предоставленное в полезных данных запроса во время создания отчета
`ReportStatus`	Состояние выполнения отчета. Возможные значения: Paused (Приостановлено), Active (Активно) и Inactive (Неактивно).
`RecurrenceInterval`	Интервал повторения, предоставленный в полезных данных запроса во время создания отчета
`RecurrenceCount`	Оставшееся число повторений для отчета
`CallbackUrl`	URL-адрес обратного вызова, предоставленный в полезных данных запроса во время создания отчета
`CallbackMethod`	Метод обратного вызова, предоставленный в полезных данных запроса во время создания отчета
`Format`	Формат файлов отчета, предоставленных в полезных данных запроса во время создания отчета
`EndTime`	Время окончания, предоставленное в полезных данных запроса во время создания отчета. Это применимо только в том случае, если `ExecuteNow` задано значение True
`TotalRecurrenceCount`	`RecurrenceCount` в полезных данных запроса во время создания отчета
`nextExecutionStartTime`	Метка времени UTC при запуске следующего отчета
`TotalCount`	Число записей в массиве значений
`StatusCode`	Код результата. Возможные значения — 200, 400, 401, 403, 500
`message`	Сообщение о состоянии из выполнения API

Получение сведений об API выполнения отчетов

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

Внимание

В этом API параметры executionStatus=Completed и getLatestExecution=true имеют значения по умолчанию. В связи с этим вызов API до первого успешного выполнения отчета возвращает 404. Для получения ожидающих выполнений можно использовать параметр executionStatus=Pending.

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

Способ	URI запроса
Получить	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

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

Верхний колонтитул	Тип	Описание
Авторизация	строка	Обязательный. Маркер доступа Microsoft Entra. Формат — `Bearer <token>`.
Content type	строка	`application/json`

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

нет

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

Наименование параметра	Обязательное поле	Type	Описание
`reportId`	Да	строка	Фильтр для получения сведений о выполнении только отчетов с параметром `reportId`, указанным в этом аргументе.
`executionId`	Нет	строка	Фильтр для получения сведений только об отчетах с параметром `executionId`, указанным в этом аргументе. Несколько `executionIds` можно указать, разделив их точкой с запятой ";".
`executionStatus`	No	string/enum	Фильтр для получения сведений только об отчетах с параметром `executionStatus`, указанным в этом аргументе. Допустимые значения: `Pending`, `Running`, `Paused` и `Completed` Значение по умолчанию — `Completed`.
`getLatestExecution`	No	boolean	API возвратит сведения о последнем выполнении отчета. По умолчанию этот параметр имеет значение `true`. Если вы решите передать значение этого параметра в виде `false`, API возвратит экземпляры выполнения за последние 90 дней.

Полезные данные запроса

нет

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

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

Коды отклика: 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.

Словарь терминов

Основные определения элементов в ответе.

Параметр	Описание
`ExecutionId`	Универсальный уникальный идентификатор (UUID) экземпляра выполнения
`ReportId`	Идентификатор отчета, связанный с экземпляром выполнения
`RecurrenceInterval`	Интервал повторений, предоставленный при создании отчета.
`RecurrenceCount`	Число повторений, указанное при создании отчета
`CallbackUrl`	URL-адрес обратного вызова, связанный с экземпляром выполнения
`CallbackMethod`	Метод обратного вызова, предоставленный в полезных данных запроса во время создания отчета
`Format`	Формат созданного файла по завершении выполнения
`ExecutionStatus`	Состояние экземпляра выполнения отчета. Допустимые значения: `Pending`, `Running`, `Paused` и `Completed`
`ReportLocation`	Расположение, где скачан отчет.
`ReportAccessSecureLink`	Ссылка для безопасного доступа к отчету
`ReportExpiryTime`	Время, при наступлении которого истекает срок действия ссылки на отчет, в формате UTC: гггг-мм-ddTчч: мм: ссZ
`ReportGeneratedTime`	Время создания отчета в формате UTC: гггг-мм-ddTHH: мм: ссZ
`EndTime`	Время окончания, предоставленное в полезных данных запроса во время создания отчета. Это применимо только в том случае, если `ExecuteNow` задано значение True
`TotalRecurrenceCount`	`RecurrenceCount` в полезных данных запроса во время создания отчета
`nextExecutionStartTime`	Метка времени UTC при запуске следующего отчета
`TotalCount`	Число наборов данных в массиве Value.
`StatusCode`	Код результата Возможные значения: 200, 400, 401, 403, 404 и 500
`message`	Сообщение о состоянии из выполнения API

Вы можете поработать с API-интерфейсами с помощью URL-адреса API Swagger.

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

Поделиться через

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

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

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

API создания отчетов

Получение сведений об API выполнения отчетов

Обратная связь

Дополнительные ресурсы

Поделиться через

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

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

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

API создания отчетов

Получение сведений об API выполнения отчетов

Связанный контент

Обратная связь

Дополнительные ресурсы