API выверки выставленных счетов версии 2 (GA)
Область применения: Центр партнеров (недоступно в национальном облаке)
Наш асинхронный API предлагает более быстрый и управляемый способ доступа к данным выставления счетов и выверки через большие двоичные объекты Azure. С помощью этого API не нужно оставаться открытым подключением в течение нескольких часов или выполнять цикл по пакетам из 2000 элементов строки за раз.
Мы оптимизированы для нашей новой коммерческой платформы API выверки счетов с помощью ключа валета и асинхронных шаблонов ответа на запросы. Этот API предоставляет маркер подписанного URL-адреса (SAS), который можно использовать для доступа ко всем атрибутам или подмножества оплачиваемых данных выверки счетов.
Примечание.
Новый API не размещен на узле API Центра партнеров. Вместо этого его можно найти на MS Graph на странице использования API Microsoft Graph для экспорта данных о выставлении счетов партнеров — Microsoft Graph версии 1.0. Чтобы получить доступ к этому API, ознакомьтесь со следующими сведениями.
Внимание
Чтобы предоставить приложению необходимые разрешения для доступа к данным о выставлении счетов партнера, необходимо выполнить эту ссылку и узнать об основах проверки подлинности и авторизации для Microsoft Graph.
Как правило, вы можете использовать портал Azure или Центр администрирования Entra для назначения требуемого разрешения: PartnerBilling.Read.All. Ниже приведены шаги по созданию следующих действий.
- Зарегистрируйте приложение на домашней странице Microsoft Entra в разделе Регистрация приложений.
- Назначьте приложению разрешение на странице приложения Microsoft Entra App в разделе разрешений API. Выберите "Добавить разрешение" и выберите область "PartnerBilling.Read.All".
Обзор API
Чтобы получить асинхронные данные о выверке счетов о выставлении счетов, используйте две конечные точки API. Вот как это делается:
Конечная точка выверки выставленного счета
Используйте этот API для получения новых выставленных счетов по выверке счетов. API возвращает состояние HTTP 202 и заголовок расположения, содержащий URL-адрес. Опросите этот URL-адрес через регулярные интервалы, пока не получите состояние успешного выполнения с URL-адресом манифеста.
Конечная точка состояния операции
Чтобы получить состояние успешного выполнения, продолжайте вызывать этот API через регулярный интервал. Если данные не готовы, ответ 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 | Идентификатор клиента партнера. |
| rootDirectory | Корневой каталог файла. |
| sasToken | Маркер SAS (подписанный URL-адресом), позволяющий считывать все файлы в каталоге. |
| partitionType | Делит данные на несколько больших двоичных объектов на основе атрибута partitionValue . Система разделяет секции, превышающие поддерживаемую цифру. По умолчанию данные секционируются на основе количества элементов строки в файле. Не устанавливайте фиксированное количество строк или размер файла в коде, так как эти значения могут измениться. |
| BLOBCount | Общее количество файлов для этого идентификатора клиента партнера. |
| большие двоичные объекты | Массив JSON объектов "BLOB-объектов", содержащий сведения о файле для идентификатора клиента партнера. |
| большой двоичный объект | Объект, содержащий следующие сведения: имя: имя большого двоичного объекта. partitionValue: Секция, содержащая файл. Большая секция разделена на несколько файлов, причем каждый файл содержит один и тот же "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 полезных данных манифеста. служба хранилища Azure пакет SDK/tool для скачивания и распакуйте файл БОЛЬШОго двоичного объекта. Он находится в формате 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#.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по