API выверки выставленных счетов версии 2 (GA)
Область применения: Центр партнеров (недоступно в национальном облаке)
Наш новый асинхронный API предлагает более быстрый и эффективный способ доступа к данным выставления счетов и выверки через большие двоичные объекты Azure. Вместо того чтобы держать соединение открытым в течение нескольких часов или обрабатывать пакеты из 2000 элементов строки, теперь можно оптимизировать рабочий процесс, уменьшить нагрузку на сервер и улучшить время обработки данных.
Новый API выверки выставленных счетов в коммерческой торговле использует расширенные методы, такие как ключ валета и асинхронные шаблоны ответа на запросы. Шаблон ключа valet позволяет обеспечить безопасный доступ к ресурсам без предоставления общего доступа к учетным данным, а шаблон асинхронного ответа на запросы обеспечивает эффективное взаимодействие между системами.
Этот API предоставляет маркер подписанного URL-адреса (SAS), который можно использовать для доступа ко всем атрибутам или подмножества оплачиваемых данных выверки счетов. Этот маркер повышает безопасность путем предоставления ограниченного времени доступа и обеспечивает гибкость в управлении разрешениями на доступ к данным.
Благодаря внедрению оптимизированных 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"
}
Параметры запроса
Н/П
Текст запроса
| Атрибут | Обязательное поле | Type | Описание |
|---|---|---|---|
| attributeSet | False | Строка | Выберите "полный" для всех атрибутов или "базовый" для ограниченного набора. Если значение по умолчанию не указано, значение full. Проверьте список атрибутов в этом разделе. Необязательно. |
| invoiceId | Истина | Строка | Уникальный идентификатор для каждого счета. Необходимые. |
Заголовки запросов
Заголовок запроса для 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 | Истина | Уникальный идентификатор для каждого ответа Необходимые. |
| статус | Истина |
Значения и действия: обязательный. не начато: дождитесь указанного времени ожидания в заголовке 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": "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"
}
\]
}
}
Шаг 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 выверки выставленных счетов для полных или базовых наборов атрибутов, см. в этой таблице. Дополнительные сведения об этих атрибутах и их значениях см. в этом руководстве .
| Атрибут | Полностью | Базовая |
|---|---|---|
| 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 версии 1 в версию 2.
- Теперь каждое имя атрибута начинается с буквы верхнего регистра, чтобы обеспечить согласованность с файлом и повысить удобочитаемость.
Пример кода
Чтобы использовать этот API, см. следующую ссылку, включающую пример кода C#.