API выверки выставленных счетов версии 2 (GA)
Применяется к: Центр партнеров (недоступен в Azure для государственных организаций или Azure China 21Vianet)
Общие сведения об архитектуре
Новый асинхронный API предлагает значительные улучшения в том, как мы обрабатываем доступ к данным выставления счетов и выверки. Этот подход устраняет проблемы, связанные с традиционными синхронными методами, такими как обслуживание длительных подключений и обработка больших пакетов данных. Ниже приведены основные преимущества и механизмы этого API:
Ключевые компоненты
Безопасный доступ с помощью шаблона ключа для парковщика
Шаблон ключа для сотрудников обеспечивает безопасный и ограниченный доступ к вашим платежным данным. Аналогично тому, как служебный ключ позволяет кому-то управлять автомобилем без доступа к багажнику, этот шаблон обеспечивает детализированный контроль доступа. Вместо использования общих учетных данных токен совместного доступа (SAS) предоставляет ограниченный по времени доступ к определённым ресурсам. Этот шаблон снижает риск несанкционированного доступа, настраивая точные сроки действия и разрешения доступа.
Повышение эффективности с помощью асинхронного шаблона ответа на запрос
Подумайте об этом, как о заказе в оживлённом ресторане. Вместо того чтобы ждать у стойки, вы получаете зуммер и можете заниматься другими делами, пока готовится ваш заказ. Когда данные будут готовы, система уведомляет вас.
Асинхронный характер API означает, что вы выполняете запрос и система обрабатывает его в фоновом режиме. Это асинхронный запрос-ответ эффективно использует ресурсы, снижает нагрузку на сервер и минимизирует тайм-ауты и сбои, которые часто встречаются при синхронном извлечении данных.
Гибкость в разрешениях доступа к данным
Маркеры SAS обеспечивают гибкость в управлении разрешениями доступа к данным. Вы можете создавать токены, предоставляющие доступ ко всем атрибутам данных согласования выставленных счетов или ограничить доступ к определенным подмножествам. Эта степень детализации позволяет организациям адаптировать доступ к данным в соответствии с внутренними политиками и нормативными требованиями, повышая безопасность и соответствие требованиям.
Упрощенный рабочий процесс и улучшенное время обработки данных
Шаблон асинхронного ответа на запрос упрощает обработку данных, позволяя динамический доступ вместо фиксированных пакетов из 2000 элементов строки. Такой подход приводит к более быстрым результатам и улучшению времени обработки, упрощая интеграцию данных выставления счетов и выверки в существующие системы и рабочие процессы.
Преимущества
преимущества производительности
Вместо поддержания длительных подключений и обработки фиксированных пакетов новая система позволяет:
- Выполните быстрый первоначальный запрос.
- Получите маркер безопасного доступа.
- Обрабатывайте данные в своём темпе.
- Доступ именно к тому, что вам нужно, когда это необходимо.
улучшения безопасности
Шаблон ключа valet, реализованный с помощью маркеров SAS, предоставляет следующие возможности:
- Ограниченный доступ по времени.
- Ограниченные разрешения.
- Устранение общего доступа или хранения постоянных учетных данных.
- Детализированное управление доступом.
Архитектурные преимущества
Шаблон асинхронного запроса-ответа действует как личный помощник, который:
- Принимает ваш запрос.
- Обрабатывает задачу в фоновом режиме.
- Уведомляет вас, когда все готово.
Внедрение оптимизированных API для повышения производительности
Использование этих оптимизированных API упрощает рабочий процесс и повышает общую производительность управления данными. Используя безопасный контроль доступа и эффективные механизмы извлечения, вы достигаете лучшие результаты с меньшими усилиями, что приводит к повышению эффективности работы.
В заключение, новый асинхронный API для доступа к данным выставления счетов и выверки через Azure blobs является мощным инструментом. Он обеспечивает безопасный, эффективный доступ к финансовым данным, упрощение рабочих процессов, снижение нагрузки сервера и улучшение времени обработки, все с высоким уровнем безопасности и соответствия требованиям.
Примечание.
Новый API не размещен на узле API Центра партнеров. Вместо этого вы можете найти это на платформе Microsoft Graph: используйте API Microsoft Graph, чтобы экспортировать данные о выставлении счетов для партнеров — версия 1.0. Чтобы получить доступ к этому API, ознакомьтесь со следующими сведениями.
Разрешить приложению безопасно получать доступ к данным о выставлении счетов партнера
Чтобы разрешить приложению доступ к данным о выставлении счетов партнера, следуйте этой ссылке и ознакомьтесь с основами проверки подлинности и авторизации MicrosoftGraph. Этот шаг имеет решающее значение, так как это гарантирует, что ваше приложение может безопасно получить доступ к необходимым данным.
Зарегистрируйте ваше приложение и предоставьте разрешение PartnerBilling.Read.All
Вы можете назначить разрешение "PartnerBilling.Read.All" с помощью портала Azure или центра администрирования Microsoft Entra. Выполнив эти действия, вы можете убедиться, что ваше приложение имеет необходимый доступ к данным о выставлении счетов партнера. Это делается следующим образом:
- Зарегистрируйте приложение на домашней странице Microsoft Entra в разделе Регистрация приложений.
- Предоставьте необходимое разрешение, перейдя на страницу приложения Microsoft Entra. В разделе разрешений API выберите Добавить разрешение и выберите область PartnerBilling.Read.All.
Сведения о ключевых конечных точках API
Чтобы помочь вам асинхронно получать строки выверки счетов за новые виды коммерции, мы предлагаем два ключевых конечных пункта API. Эти конечные точки помогают эффективно управлять процессом выверки счетов. Выполните это упрощенное руководство, чтобы быстро приступить к работе.
Используйте конечную точку выверки выставленного счета
Во-первых, используйте этот API для получения позиций сверки по счетам для новой коммерции. При выполнении запроса вы получаете состояние HTTP 202 и заголовок расположения с URL-адресом. Регулярно опросите этот URL-адрес, пока не получите состояние успешного выполнения и URL-адрес манифеста.
Используйте конечную точку статуса операции
Затем продолжайте проверять состояние операции, вызывая этот API через регулярные интервалы. Если данные не готовы, ответ включает заголовок Retry-After , указывающий, как долго ждать, прежде чем повторить попытку. После завершения операции вы получите манифест-ресурс со ссылкой на папку для загрузки данных об использовании. Ответ сегментирует файлы, чтобы повысить пропускную способность и разрешить параллелизм ввода-вывода.
Просмотр схемы последовательности
Ниже приведена диаграмма последовательности, которая показывает шаги для загрузки новых данных о согласовании коммерческих счетов.
Следуйте последовательности действий пользователя, чтобы получить данные выверки выставленных счетов
Ниже приведена последовательность действий пользователя для получения данных выверки выставленных счетов:
- Отправить запрос POST
- Проверить состояние запроса
- Загрузить элементы строки выверки из хранилища Azure Blob
Отправка запроса POST
Отправьте запрос 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"
}
Параметры запроса
Н/П
Текст запроса
| Атрибут | Обязательное поле | Тип | Описание |
|---|---|---|---|
| набор атрибутов | Ложь | Строка | Выберите "полный" для всех атрибутов или "базовый" для ограниченного набора. Если не указано иное, значение по умолчанию — "full". Проверьте список атрибутов в этом разделе. Необязательно. |
| идентификатор счета | Истина | Строка | Уникальный идентификатор для каждого счета. Обязательно. |
Заголовки запросов
Используйте заголовки запроса для 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-адрес, указанный в заголовке расположения. |
Проверка состояния запроса
Чтобы отслеживать состояние запроса, убедитесь, что вы получите ответ HTTP 200, который является стандартным кодом состояния, указывающим на "успешно" или "сбой". В случае успешного выполнения вы найдете URL-адрес манифеста в атрибуте resourceLocation. Этот атрибут предоставляет конечную точку для доступа к необходимым сведениям.
Получение состояния операции
Извлекает состояние запроса.
Запрос API
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Параметры запроса
| Имя. | Включить в | Обязательное поле | Тип | Описание |
|---|---|---|---|---|
| operationId | URI запроса | Истина | Строка | Уникальный идентификатор для проверки состояния запроса. Обязательно. |
Заголовок запроса
Заголовки запроса для API с использованием шагов, перечисленных в Рекомендации по использованию Microsoft Graph. Следуя этим рекомендациям, вы гарантируете надежность и поддержку приложения. Ваше внимание на этом шаге имеет решающее значение для простой интеграции и оптимальной производительности.
Текст запроса
Недоступно
Состояние ответа
Помимо стандартных статусов HTTP, перечисленных в стандартных статусах ответа API, API также может возвращать следующий статус HTTP:
| Код | Описание |
|---|---|
| 410 – Ушло | Действие ссылки манифеста истекает через заданный период времени. Чтобы снова получить ссылку манифеста, отправьте новый запрос. |
Нагрузка ответа
Полезные данные ответа API включают следующие атрибуты:
| Атрибут | Обязательное поле | Описание |
|---|---|---|
| id | Истина | Уникальный идентификатор для каждого ответа Требуется. |
| статус | Истина |
Значения и действия: обязательный. не начато: дождитесь указанного времени ожидания в заголовке Retry-After, а затем сделайте повторный запрос для проверки состояния. запуск: подождите указанное в заголовке "Retry-After" время, затем сделайте повторный запрос для проверки состояния. Выполнено успешно: данные готовы. Извлеките полезные данные манифеста с помощью URI, указанного в resourceLocation. неудача: операция потерпела неудачу окончательно. Перезапустите его. |
| время создания | Истина | Время выполнения запроса. Обязательно. |
| дата_и_время_последнего_действия | Истина | При последнем изменении состояния. Обязательно. |
| расположение ресурса | Ложь | URI для полезной нагрузки манифеста. Необязательно. |
| ошибка | Ложь | Сведения о любых ошибках, предоставляемых в формате JSON. Необязательно. Включенные атрибуты: сообщение: описание ошибки. код: тип ошибки. |
Объект расположения ресурсов
| Атрибут | Описание |
|---|---|
| id | Уникальный идентификатор манифеста. |
| schemaVersion | Версия схемы манифеста. |
| формат данных | Формат файла данных выставления счетов. compressedJSON: формат данных, в котором каждый BLOB представляет собой сжатый файл, содержащий данные в формате строк JSON. Чтобы получить данные из каждого BLOB, распакуйте его. |
| createdDateTime | Дата и время создания файла манифеста. |
| eTag | Версия данных манифеста. Новое значение создается всякий раз при изменении сведений о выставлении счетов. |
| partnerTenantId | Идентификатор Microsoft Entra клиента партнера. |
| rootDirectory | Корневой каталог файла. |
| токен SAS | Маркер SAS (маркер общего доступа), позволяющий считывать все файлы в каталоге. |
| тип раздела | Делит данные на несколько больших двоичных объектов на основе атрибута partitionValue . Система разделяет секции, превышающие поддерживаемую цифру. По умолчанию данные секционируются на основе количества элементов строки в файле. Избегайте жёсткой кодировки количества строк или размеров файлов, так как они могут измениться. |
| blobCount | Общее количество файлов для этого идентификатора клиента партнера. |
| большие двоичные объекты | Массив JSON объектов "BLOB-объектов", содержащий сведения о файле для идентификатора клиента партнера. |
| объект BLOB | Объект, содержащий следующие сведения: name и partitionValue |
| имя | Имя двоичного объекта. |
| 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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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"
}
\]
}
}
Скачивание элементов линии выверки из хранилища BLOB-объектов Azure
Сначала необходимо получить маркер SAS и расположение хранилища BLOB (объедините корневой каталог и имя BLOB). Ищите эти сведения в свойствах sasToken, rootDirectoryи blobs ответа манифеста API полезной нагрузки.
Чтобы продолжить, выполните следующие действия.
- Скачайте файл Blob с помощью SDK или инструмента для хранения Azure.
- Распакуируйте файл, который находится в формате JSONLines.
Совет
Обязательно ознакомьтесь с нашим примером кода . Показано, как скачать и распаковать файл Blob Azure на локальный диск.
Стандартные состояния ответа API
Вы можете получить следующие состояния HTTP из ответа API:
| Код | Описание |
|---|---|
| 400 — недопустимый запрос | Запрос отсутствует или содержит неверные данные. Проверьте текст ответа для получения сведений об ошибке. |
| 401 — не авторизовано; | Перед первым вызовом требуется проверка подлинности. Проверка подлинности с помощью службы API партнера. |
| 403 — запрещено; | У вас нет необходимой авторизации для выполнения запроса. |
| 404 — не найден | Запрошенные ресурсы недоступны с предоставленными входными параметрами. |
| 410 – Ушло | Ссылка на манифест уже недействительна или неактивна. Отправьте новый запрос. |
| 500 — внутренняя ошибка сервера | API или его зависимости не могут выполнять запрос прямо сейчас. Повторите попытку позже. |
| 5000 — нет доступных данных | Система не имеет данных для предоставленных входных параметров. |
Сравнение базовых и полных атрибутов выверки счетов
Чтобы сравнить атрибуты, возвращаемые API сверки оплаченных счетов для наборов атрибутов "полных" или "базовых", обратитесь к этой таблице. Чтобы узнать больше об этих атрибутах и их значениях, см. раздел о том, как использовать файл выверки.
| Атрибут | Полностью | Базовая |
|---|---|---|
| PartnerId | да | да |
| Идентификатор клиента | да | да |
| CustomerName | да | да |
| ИмяДоменаКлиента | да | нет |
| СтранаКлиента | да | нет |
| НомерСчета | да | да |
| MpnId | да | нет |
| Tier2MpnId | да | да |
| ИД заказа | да | да |
| Дата заказа | да | да |
| ИД продукта | да | да |
| Идентификатор SKU | да | да |
| Идентификатор доступности | да | да |
| SkuName | да | нет |
| НаименованиеПродукта | да | да |
| Тип заряда | да | да |
| Цена за единицу | да | да |
| Количество | да | нет |
| Промежуточный итог | да | да |
| Общая сумма налога | да | да |
| Итог | да | да |
| Валюта | да | да |
| Описание коррекции цены | да | да |
| PublisherName | да | да |
| Идентификатор издателя | да | нет |
| Описание подписки | да | нет |
| Идентификатор подписки | да | да |
| ДатаНачалаНачисления | да | да |
| Дата окончания начисления | да | да |
| Срок и платежный цикл | да | да |
| ЭффективнаяЦенаЗаЕдиницу | да | да |
| ТипЕдиницы | да | нет |
| AlternateId | да | нет |
| BillableQuantity | да | да |
| Частота выставления счетов | да | нет |
| ВалютаЦен | да | да |
| PCToBCExchangeRate | да | да |
| Дата обменного курса PC на BC | да | нет |
| Описание счетчика | да | нет |
| ИдентификаторЗаказаБронирования | yes | да |
| КодПричиныКредита | да | да |
| ДатаНачалаПодписки | да | да |
| ДатаОкончанияПодписки | да | да |
| Идентификатор ссылки | да | да |
| ProductQualifiers | да | нет |
| Идентификатор акции | да | да |
| КатегорияПродукта | да | да |
Внимание
Каждое поле или имя атрибута начинается с буквы верхнего регистра, чтобы обеспечить согласованность с файлом и повысить удобочитаемость.
Пример кода
Если вам нужна помощь по миграции в этот API, обратитесь к ссылке, включающей пример кода C#.
примеры API для получения данных о выверке счетов из Партнерского центра.