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

Область применения: Центр партнеров (недоступно в национальном облаке)

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

Новый API выверки выставленных счетов в коммерческой торговле использует расширенные методы, такие как ключ валета и асинхронные шаблоны ответа на запросы. Этот API предоставляет маркер подписанного URL-адреса (SAS), который можно использовать для доступа ко всем атрибутам или подмножества оплачиваемых данных выверки счетов.

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

Обзор 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 "Стандартный".

Шаг 2. Проверка состояния запроса

Чтобы отслеживать состояние запроса, убедитесь, что вы получите ответ HTTP 200, указывающий на "успешно" или "неудачно". В случае успешного выполнения вы найдете URL-адрес манифеста в атрибуте resourceLocation. Этот атрибут предоставляет конечную точку для доступа к необходимым сведениям.

Получение состояния операции

Извлекает состояние запроса.

Запрос API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

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

Заголовок запроса

Заголовок запроса для API, выполнив действия, описанные в рекомендациях по использованию Microsoft Graph. Следуя этим рекомендациям, вы гарантируете надежность и поддержку приложения. Ваше внимание на этом шаге имеет решающее значение для простой интеграции и оптимальной производительности.

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

Недоступно

Состояние ответа

Помимо стандартных состояний HTTP, перечисленных в состояниях ответа API уровня "Стандартный", API также может возвращать следующее состояние HTTP:

Полезные данные ответа

Полезные данные ответа API включают следующие атрибуты:

Объект расположения ресурсов

Запрос 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 .

Стандартные состояния ответа API

Эти состояния HTTP можно получить из ответа API:

Атрибуты строки выверки выставленного счета

Чтобы сравнить атрибуты, возвращаемые API выверки выставленного счета для наборов атрибутов full или basic, см. в следующей таблице. Дополнительные сведения об этих атрибутах см. в разделе "Использование файла рекогносцировки".

Пример кода

Чтобы использовать этот API, см. следующую ссылку, включающую пример кода C#.

Примеры для партнеров-Center-Billing-Recon-Samples: примеры для получения данных о рекогносцировке выставления счетов из Центра партнеров (github.com).