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

API выверки выставленных счетов версии 2 (GA)

  • Статья

Центр партнеров (недоступен в Azure для государственных организаций или Azure China 21Vianet) применяется к:

Общие сведения об архитектуре

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

Ключевые компоненты

Безопасный доступ с помощью шаблона ключа valet

Шаблон ключа валета обеспечивает безопасный и ограниченный доступ к данным биллинга. Аналогично тому, как служебный ключ позволяет кому-то управлять автомобилем без доступа к багажнику, этот шаблон обеспечивает детализированный контроль доступа. Вместо использования общих учетных данных токен совместного доступа (SAS) предоставляет ограниченный по времени доступ к определённым ресурсам. Этот шаблон снижает риск несанкционированного доступа, настраивая точные сроки действия и разрешения доступа.

Повышение эффективности с помощью асинхронного шаблона ответа на запрос

Подумайте об этом, как о заказе в оживлённом ресторане. Вместо того чтобы ждать у стойки, вы получаете зуммер и можете заниматься другими делами, пока готовится ваш заказ. Когда данные будут готовы, система уведомляет вас.

Асинхронный характер API означает, что вы выполняете запрос и система обрабатывает его в фоновом режиме. Это асинхронный запрос-ответ эффективно использует ресурсы, снижает нагрузку на сервер и минимизирует тайм-ауты и сбои, которые часто встречаются при синхронном извлечении данных.

Гибкость в разрешениях доступа к данным

Маркеры SAS обеспечивают гибкость в управлении разрешениями доступа к данным. Вы можете создавать токены, предоставляющие доступ ко всем атрибутам данных согласования выставленных счетов или ограничить доступ к определенным подмножествам. Эта степень детализации позволяет организациям адаптировать доступ к данным в соответствии с внутренними политиками и нормативными требованиями, повышая безопасность и соответствие требованиям.

Упрощенный рабочий процесс и улучшенное время обработки данных

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

Преимущества

  1. преимущества производительности

    Вместо поддержания длительных подключений и обработки фиксированных пакетов новая система позволяет:

    • Выполните быстрый первоначальный запрос.

    • Получите маркер безопасного доступа.

    • Обрабатывайте данные в своём темпе.

    • Доступ именно к тому, что вам нужно, когда это необходимо.

  2. улучшения безопасности

    Шаблон ключа valet, реализованный с помощью маркеров SAS, предоставляет следующие возможности:

    • Ограниченный доступ по времени.

    • Ограниченные разрешения.

    • Устранение общего доступа или хранения постоянных учетных данных.

    • Мелкозернистое управление доступом.

  3. Архитектурные преимущества

    Шаблон асинхронного запроса-ответа действует как личный помощник, который:

    • Принимает ваш запрос.

    • Обрабатывает задачу в фоновом режиме.

    • Уведомляет вас, когда все готово.

Внедрение оптимизированных 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. Выполнив эти действия, вы можете убедиться, что ваше приложение имеет необходимый доступ к данным о выставлении счетов партнера. Это делается следующим образом:

  1. Зарегистрируйте приложение на домашней странице Microsoft Entra в разделе Регистрация приложений.
  2. Предоставьте необходимое разрешение, перейдя на страницу приложения Microsoft Entra. В разделе разрешений API выберите Добавить разрешение и выберите область PartnerBilling.Read.All.

Сведения о ключевых конечных точках API

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

Используйте конечную точку выверки выставленного счета

Во-первых, используйте этот API для получения новых выставленных счетов, выставленных на выверку счетов. При выполнении запроса вы получаете состояние HTTP 202 и заголовок расположения с URL-адресом. Регулярно опросите этот URL-адрес, пока не получите состояние успешного выполнения и URL-адрес манифеста.

Используйте конечную точку статуса операции

Затем продолжайте проверять состояние операции, вызывая этот API через регулярные интервалы. Если данные не готовы, ответ включает заголовок Retry-After , указывающий, как долго ждать, прежде чем повторить попытку. После завершения операции вы получите манифест-ресурс со ссылкой на папку для загрузки данных об использовании. Ответ сегментирует файлы, чтобы повысить пропускную способность и разрешить параллелизм ввода-вывода.

Просмотр схемы последовательности

Ниже приведена схема последовательности, на которую показано, как скачать новые данные о выверки торгового счета.

диаграмма, показывающая этапы загрузки данных выверки.

Следуйте последовательности действий пользователя, чтобы получить данные выверки выставленных счетов

Ниже приведена последовательность действий пользователя для получения данных выверки выставленных счетов:

Отправка запроса 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"

}

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

Н/П

Текст запроса

Атрибут Обязательное поле 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-адрес, указанный в заголовке расположения.

Проверка состояния запроса

Чтобы отслеживать состояние запроса, убедитесь, что вы получите ответ 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"

            }

        \]

    }

}

Скачивание элементов линии выверки из хранилища BLOB-объектов Azure

Сначала необходимо получить токен общего доступа (SAS) и определить расположение хранилища блобов. Найдите эти сведения в свойствах sasToken и rootDirectory ответа API на данные манифеста.

Чтобы продолжить, выполните следующие действия.

  1. Скачайте файл Blob с помощью SDK или инструмента для хранения Azure.
  2. Распакуируйте файл, который находится в формате 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, обратитесь к ссылке, включающей пример кода C#.

примеры API для получения данных о выверке счетов из Партнерского центра.

Связанное содержимое