API выверки выставленных счетов версии 2 (GA)
Область применения: Центр партнеров (недоступно в национальном облаке)
Наш новый асинхронный API предлагает более быстрый и эффективный способ доступа к данным выставления счетов и выверки через большие двоичные объекты Azure. Вместо того, чтобы держать подключение открытым в течение нескольких часов или обрабатывать пакеты из 2000 элементов строки, теперь можно упростить рабочий процесс.
Новый API выверки выставленных счетов в коммерческой торговле использует расширенные методы, такие как ключ валета и асинхронные шаблоны ответа на запросы. Этот API предоставляет маркер подписанного URL-адреса (SAS), который можно использовать для доступа ко всем атрибутам или подмножества оплачиваемых данных выверки счетов.
Наш API использует оптимизированные методы для повышения эффективности, поэтому вы можете добиться более быстрых результатов с меньшими усилиями. Обнимайте этот API, чтобы упростить доступ к данным и повысить общую эффективность.
Примечание.
Новый API не размещен на узле API Центра партнеров. Вместо этого его можно найти на MS Graph на странице использования API Microsoft Graph для экспорта данных о выставлении счетов партнеров — Microsoft Graph версии 1.0. Чтобы получить доступ к этому API, ознакомьтесь со следующими сведениями.
Внимание
Чтобы разрешить приложению доступ к данным о выставлении счетов партнера, следуйте этой ссылке и ознакомьтесь с основами проверки подлинности и авторизации для Microsoft Graph.
Вы можете назначить разрешение PartnerBilling.Read.All с помощью портал Azure или Центра администрирования Entra. Это делается следующим образом:
- Зарегистрируйте приложение на домашней странице Microsoft Entra в разделе Регистрация приложений.
- Чтобы предоставить необходимое разрешение, перейдите на страницу приложения Microsoft Entra в разделе разрешений API. Выберите "Добавить разрешение" и выберите область "PartnerBilling.Read.All".
Выполнив эти действия, вы убедитесь, что ваше приложение имеет необходимый доступ к данным о выставлении счетов партнера.
Обзор API
Чтобы получить асинхронные элементы выверки выставленных счетов о выставлении счетов, мы предлагаем две ключевые конечные точки API. Ниже приведено упрощенное руководство по началу работы:
Конечная точка выверки выставленного счета
Во-первых, используйте этот API для получения новых выставленных счетов, выставленных на выверку счетов. При выполнении запроса вы получаете состояние HTTP 202 и заголовок расположения с URL-адресом. Регулярно опросите этот URL-адрес, пока не получите состояние успешного выполнения и URL-адрес манифеста.
Конечная точка состояния операции
Затем продолжайте проверять состояние операции, вызывая этот API через регулярные интервалы. Если данные не готовы, ответ включает заголовок Retry-After , указывающий, как долго ждать, прежде чем повторить попытку. После завершения операции вы получите ресурс манифеста со ссылкой на папку хранилища, чтобы скачать данные об использовании. Ответ сегментирует файлы, чтобы повысить пропускную способность и разрешить параллелизм ввода-вывода.
Выполнив следующие действия, вы можете эффективно управлять процессом выверки счетов.
Схема последовательностей
Ниже приведена схема последовательности, на которую показано, как скачать новые данные о выверки торгового счета.
Последовательность действий пользователя
Чтобы получить данные выверки выставленных счетов, выполните следующие действия.
Шаг 1. Отправка запроса
Отправьте запрос POST в конечную точку API.
Получение элементов линии выверки выставленного счета
Запрос API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Параметры запроса
Н/П
Текст запроса
Заголовки запросов
Заголовок запроса для API, выполнив действия, описанные в рекомендациях по использованию Microsoft Graph. Следуя этим рекомендациям, вы гарантируете надежность и поддержку приложения. Ваше внимание на этом шаге имеет решающее значение для простой интеграции и оптимальной производительности.
Ответ API
HTTP/1.1 202 Accepted
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API обычно отвечает с состоянием HTTP 202. Вы также можете столкнуться с другими состояниями в зависимости от ваших запросов. Эти состояния перечислены в разделе состояния ответа API "Стандартный".
| Код | Описание |
|---|---|
| 202 — принято | Ваш запрос был принят. Чтобы проверить состояние запроса, запросите URL-адрес, указанный в заголовке расположения. |
Шаг 2. Проверка состояния запроса
Чтобы отслеживать состояние запроса, убедитесь, что вы получите ответ HTTP 200, указывающий на "успешно" или "неудачно". В случае успешного выполнения вы найдете URL-адрес манифеста в атрибуте resourceLocation. Этот атрибут предоставляет конечную точку для доступа к необходимым сведениям.
Получение состояния операции
Извлекает состояние запроса.
Запрос API
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Параметры запроса
| Имя. | Включение в | Обязательное поле | Type | Описание |
|---|---|---|---|---|
| operationId | URI запроса | Истина | Строка | Уникальный идентификатор для проверки состояния запроса. Обязательный. |
Заголовок запроса
Заголовок запроса для API, выполнив действия, описанные в рекомендациях по использованию Microsoft Graph. Следуя этим рекомендациям, вы гарантируете надежность и поддержку приложения. Ваше внимание на этом шаге имеет решающее значение для простой интеграции и оптимальной производительности.
Текст запроса
Недоступно
Состояние ответа
Помимо стандартных состояний HTTP, перечисленных в состояниях ответа API уровня "Стандартный", API также может возвращать следующее состояние HTTP:
| Код | Описание |
|---|---|
| 410 – Ушло | Срок действия ссылки манифеста истекает после заданного времени. Чтобы снова получить ссылку манифеста, отправьте новый запрос. |
Полезные данные ответа
Полезные данные ответа API включают следующие атрибуты:
| Атрибут | Обязательное поле | Описание |
|---|---|---|
| id | Истина | Уникальный идентификатор для каждого ответа Необходимые. |
| статус | Истина | Значения и действия: обязательный. notstarted: подождите время, указанное в заголовке Retry-After, а затем выполните еще один вызов, чтобы проверить состояние. выполняется: подождите время, указанное в заголовке Retry-After, а затем выполните другой вызов, чтобы проверить состояние. Выполнено успешно: данные готовы. Извлеките полезные данные манифеста с помощью URI, указанного в resourceLocation. сбой: операция не удалось окончательно. Перезапустите его. |
| createdDateTime | Истина | Время выполнения запроса. Необходимые. |
| lastActionDateTime | Истина | При последнем изменении состояния. Необходимые. |
| resourceLocation | False | Универсальный код ресурса (URI) для полезных данных манифеста. Необязательно. |
| error | False | Сведения о любых ошибках, предоставляемых в формате JSON. Необязательно. Атрибуты включены: сообщение: описание ошибки. код: тип ошибки. |
Объект расположения ресурсов
| Атрибут | Описание |
|---|---|
| id | Уникальный идентификатор манифеста. |
| schemaVersion | Версия схемы манифеста. |
| dataFormat | Формат файла данных выставления счетов. compressedJSON: формат данных, в котором каждый большой двоичный объект представляет собой сжатый файл, содержащий данные в формате строк JSON . Чтобы получить данные из каждого большого двоичного объекта, распаковите его. |
| createdDateTime | Дата и время создания файла манифеста. |
| eTag | Версия данных манифеста. Новое значение создается всякий раз при изменении сведений о выставлении счетов. |
| partnerTenantId | Идентификатор Microsoft Entra клиента партнера. |
| rootDirectory | Корневой каталог файла. |
| sasToken | Маркер SAS (подписанный URL-адресом), позволяющий считывать все файлы в каталоге. |
| partitionType | Делит данные на несколько больших двоичных объектов на основе атрибута partitionValue . Система разделяет секции, превышающие поддерживаемую цифру. По умолчанию данные секционируются на основе количества элементов строки в файле. Не устанавливайте фиксированное количество строк или размер файла в коде, так как эти значения могут измениться. |
| BLOBCount | Общее количество файлов для этого идентификатора клиента партнера. |
| большие двоичные объекты | Массив JSON объектов "BLOB-объектов", содержащий сведения о файле для идентификатора клиента партнера. |
| большой двоичный объект | Объект, содержащий следующие сведения: name и partitionValue |
| name | Имя большого двоичного объекта. |
| partitionValue | Раздел, содержащий файл. Раздел, содержащий файл. Большие секции разделены на несколько файлов, каждый из которых содержит одно и то же значение partitionValue. |
Запрос API
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Ответ API
Ответ рекомендует ждать 10 секунд, прежде чем повторить попытку при обработке данных.
HTTP/1.1 200 OK
Retry-After: 10
{
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-05Z",
"status": "running"
}
Запрос API
(через 10 секунд после предыдущего запроса...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Ответ API
API возвращает состояние "успешно" и универсальный код ресурса (URI) для resourceLocation.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",
"@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",
"id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",
"createdDateTime": "2023-12-05T21:17:29Z",
"lastActionDateTime": "2023-12-05T21:18:00.8897902Z",
"status": "succeeded",
"resourceLocation": {
"id": "44e8500b-ab92-490e-8ac3-90500a1d3427",
"createdDateTime": "2023-11-06T19:58:47.513Z",
"schemaVersion": "2",
"dataFormat": "compressedJSON",
"partitionType": "default",
"eTag": "RwDrn7fbiTXy6UULE",
"partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",
"rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",
"sasToken": "{token}",
"blobCount": 1,
"blobs": \[
{
"name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",
"partitionValue": "default"
}
\]
}
}
Шаг 3. Скачивание элементов строки выверки выставленного счета из хранилища BLOB-объектов Azure
Сначала необходимо получить маркер подписанного URL-адреса (SAS) и расположение хранилища BLOB-объектов. Эти сведения можно найти в свойствах sasToken и rootDirectory ответа API полезных данных манифеста. Затем, чтобы скачать и распаковать файл БОЛЬШОго двоичного объекта, используйте пакет SDK или средство служба хранилища Azure. Он находится в формате JSONLines .
Совет
Обязательно ознакомьтесь с примером кода. В нем показано, как скачать и распаковать файл BLOB-объектов Azure в локальную базу данных.
Стандартные состояния ответа API
Эти состояния HTTP можно получить из ответа API:
| Код | Описание |
|---|---|
| 400 — недопустимый запрос | Запрос отсутствует или содержит неверные данные. Проверьте текст ответа для получения сведений об ошибке. |
| 401 — не авторизовано; | Перед первым вызовом требуется проверка подлинности. Проверка подлинности с помощью службы API партнера. |
| 403 — запрещено; | У вас нет необходимой авторизации для выполнения запроса. |
| 404 — не найден | Запрошенные ресурсы недоступны с предоставленными входными параметрами. |
| 410 – Ушло | Ссылка манифеста больше не действительна или активна. Отправьте новый запрос. |
| 500 — внутренняя ошибка сервера | API или его зависимости не могут выполнять запрос прямо сейчас. Повторите попытку позже. |
| 5000 — нет доступных данных | Система не имеет данных для предоставленных входных параметров. |
Атрибуты строки выверки выставленного счета
Чтобы сравнить атрибуты, возвращаемые API выверки выставленного счета для наборов атрибутов full или basic, см. в следующей таблице. Дополнительные сведения об этих атрибутах см. в разделе "Использование файла рекогносцировки".
| Атрибут | Полностью | Базовая |
|---|---|---|
| PartnerId | yes | yes |
| CustomerId | yes | yes |
| CustomerName | yes | yes |
| CustomerDomainName | yes | no |
| CustomerCountry | yes | no |
| InvoiceNumber | yes | yes |
| MpnId | yes | no |
| Tier2MpnId | yes | yes |
| ИД заказа | yes | yes |
| Датазаказа | yes | yes |
| ИД продукта | yes | yes |
| SkuId | yes | yes |
| AvailabilityId | yes | yes |
| SkuName | yes | no |
| НаименованиеПродукта | yes | yes |
| ChargeType | yes | yes |
| UnitPrice | yes | yes |
| Количество | yes | no |
| Промежуточный итог | yes | yes |
| TaxTotal | yes | yes |
| Итог | yes | yes |
| Валюта | yes | yes |
| PriceAdjustmentDescription | yes | yes |
| PublisherName | yes | yes |
| PublisherId | yes | no |
| SubscriptionDescription | yes | no |
| SubscriptionId | yes | yes |
| ChargeStartDate | yes | yes |
| ChargeEndDate | yes | yes |
| TermAndBillingCycle | yes | yes |
| EffectiveUnitPrice | yes | yes |
| UnitType | yes | no |
| AlternateId | yes | no |
| BillableQuantity | yes | yes |
| BillingFrequency | yes | no |
| PricingCurrency | yes | yes |
| PCToBCExchangeRate | yes | yes |
| PCToBCExchangeRateDate | yes | no |
| MeterDescription | yes | no |
| ReservationOrderId | yes | yes |
| CreditReasonCode | yes | yes |
| SubscriptionStartDate | yes | yes |
| SubscriptionEndDate | yes | yes |
| ReferenceId | yes | yes |
| ProductQualifiers | yes | no |
| Рекламный идентификатор | yes | yes |
| КатегорияПродукта | yes | yes |
Пример кода
Чтобы использовать этот API, см. следующую ссылку, включающую пример кода C#.