Api использования версии 2 для новой коммерции (бета-версия)
Область применения: Центр партнеров | Центр партнеров, управляемый 21Vianet | Центр партнеров для Microsoft Cloud for US Government
Используйте эти API для асинхронного получения новых коммерческих счетов и неоплачиваемых ежедневных данных об использовании.
Примечание.
Этот API будет нерекомендуем в ближайшее время. Чтобы обеспечить простое выполнение операций, рекомендуется выполнить миграцию в общедоступную версию. Ниже приведены подробные сведения, которые необходимо спланировать заранее.
Цель: получение оплачиваемых ежедневных строк использования для периодов выставления счетов с сентября 2022 г. до 21 января 2025 г.
Действие. Используйте этот API, но как можно скорее перейдите в общедоступную версию 2.
Цель: получение оплачиваемых ежедневных строк использования для периодов выставления счетов с 21 января 2025 г.
Действие. Использование только общедоступной версии API версии 2.
Цель: получение необязаемых ежедневных строк использования для текущих и предыдущих периодов выставления счетов до 21 января 2025 года.
Действие. Используйте этот API, но как можно скорее перейдите в общедоступную версию 2.
Цель: получение необязаемых ежедневных строк использования для текущих и предыдущих периодов выставления счетов с 21 января 2025 года.
Действие. Использование только общедоступной версии API версии 2.
Чтобы легко перейти к новым API, следуйте этой ссылке: Выставление счетов и неоплачиваемое ежедневное выверка api выверки использования версии 2 (GA).
Спасибо за ваше внимание, и мы с нетерпением ждем вашего дальнейшего успеха с нашими API выставления счетов.
Примечание.
Вы можете получить доступ к неоплачиваемой ежедневной строке использования с помощью API или портала Центра партнеров. Чтобы обеспечить точную информацию, до 24 часов для доступности. В зависимости от расположения и времени, когда счетчики сообщают об использовании, могут возникнуть дополнительные задержки.
Сначала мы ставим приоритеты по доставке оплачиваемых ежедневных данных об использовании. Иногда вы можете не видеть последние необнаруженные данные о ежедневном использовании, пока данные о выставлении счетов за предыдущий месяц не будут доступны. Получив данные о выставлении счетов, вы можете получить все обновленные необновенные данные об использовании с начала месяца.
Ваше понимание и терпение ценятся, так как мы стремимся обеспечить наиболее точную и своевременную информацию.
Внимание
Данные о ежедневном использовании не включают расходы на эти продукты:
- Резервирование Azure
- Экономичный план Azure
- Office
- Dynamics
- Microsoft Power Apps
- Программное обеспечение с бессрочной лицензией
- Подписка на программное обеспечение
- Продукт SaaS, отличный от Майкрософт или Marketplace
Обзор API
Асинхронный API — это новый метод быстрого доступа к данным выставления счетов и выверки в управляемых блоках. Это устраняет необходимость в обслуживании открытого подключения в течение нескольких часов и циклически через миллионы транзакций итеративно.
Мы используем ключ valet и асинхронные шаблоны ответа на запросы для оптимизации наших api выставления счетов и выверки для асинхронной доставки результатов. Ответы API предоставляют маркер для доступа к данным выверки со всеми атрибутами или подмножеством.
Данные об использовании можно скачать асинхронно с помощью трех новых шагов (конечных точек API). Дополнительные сведения см. в следующих разделах:
Конечная точка элемента строки использования
Используйте этот API для доступа к выставленным или неоплачиваемым элементам линии потребления. Он возвращает состояние HTTP 202 и заголовок расположения с URL-адресом, который необходимо опрашивать через регулярные интервалы, пока вы не получите состояние успешного выполнения с URL-адресом манифеста.
Конечная точка состояния операции
Пока вы не получите состояние успешного выполнения, продолжайте опрашивать этот API через регулярный интервал. Если запрошенные данные недоступны, ответ API включает заголовок Retry-After , указывающий время ожидания перед отправкой другого запроса.
Конечная точка манифеста
Эта конечная точка предоставляет папку хранения, из которой можно скачать фактические данные выставления счетов. Ответ разделяет или секционирует файлы для оптимизации пропускной способности и параллелизма ввода-вывода.
Схема последовательностей
На схеме показаны шаги, необходимые для скачивания данных выверки.
Последовательность действий пользователя
Выполните следующие действия, чтобы получить данные о выверки.
Шаг 1. Отправка запроса
Отправьте запрос POST в конечную точку API.
Получение необясченных элементов строки использования
Получение необязненных элементов строки использования для текущего или последнего календарного месяца.
Запрос API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Параметры запроса
| Имя | In | Обязательный | Тип | Description |
|---|---|---|---|---|
| fragment | Query | False | Строка | Выберите "полный" для полного ответа или "базовый" для подмножества атрибутов. Значение по умолчанию — full. См. список атрибутов в этой статье. |
| период | Query | Истина | Строка | Используйте "current" или "last", чтобы получить использование для текущего или последнего календарного месяца. Значение "last" совпадает с "предыдущим" в существующих API версии 1. |
| currencyCode | Query | Истина | Строка | Код валюты выставления счетов партнера. |
Устаревшие параметры запроса
Для более новой версии API не требуются следующие параметры URI:
| Имя | Description |
|---|---|
| Provider | Недоступно (Он возвращает все использование плана Azure и эквивалентен одному времени существующих API версии 1.) |
| hasPartnerEarnedCredit | Недоступно (возвращает все данные независимо от PEC.) |
| Размер | Недоступно |
| Смещение | Недоступно |
| seekOperation | Недоступно |
Заголовок запроса
Список заголовков запросов для API в этой статье.
Текст запроса
Недоступно
Ответ API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
API возвращает состояние HTTP 202. На основе запроса API может возвращать другое стандартное состояние.
| Имя | Description |
|---|---|
| 202 — принято | Запрос принимается. ЗапросИТЕ URL-адрес заголовка расположения операции для состояния запроса. |
Получение выставленных счетов элементов строки использования
Получение выставления счетов о выставлении счетов в течение закрытого периода выставления счетов.
Запрос API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Параметры запроса
| Имя | In | Обязательный | Тип | Description |
|---|---|---|---|---|
| invoiceId | Путь | Истина | Строка | Номер счета Центра партнеров. |
| Фрагмент | Query | False | Строка | Выберите "полный" для полного ответа или "базовый" для подмножества атрибутов. Значение по умолчанию — full. См. список атрибутов в этой статье. |
Устаревшие параметры запроса
Для более новой версии API не требуются следующие параметры URI:
| Имя | Description |
|---|---|
| Provider | Недоступно (Он возвращает все использование плана Azure и эквивалентен одному времени существующих API версии 1.) |
| hasPartnerEarnedCredit | Недоступно (возвращает все данные независимо от PEC.) |
| Размер | Недоступно |
| Смещение | Недоступно |
| seekOperation | Недоступно |
Заголовок запроса
Список заголовков запросов для API в этой статье.
Текст запроса
Недоступно
Ответ API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
API возвращает значение HTTP 202 Accepted. На основе API запросов может возвращать другое стандартное состояние.
| Имя | Description |
|---|---|
| 202 — принято | Запрос принимается. Проверьте состояние запроса, проверив URL-адрес заголовка расположения операции. |
Шаг 2. Проверка состояния запроса
Дождитесь успешного или неудачного состояния терминала HTTP 200. URL-адрес манифеста — это свойство resourceLocation в состоянии успешного выполнения.
Получение статуса операции
Возвращает состояние запроса на выверку данных.
Запрос API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Параметры запроса
| Имя | In | Обязательный | Тип | Description |
|---|---|---|---|---|
| operationId | Путь | Истина | Строка | Идентификатор операции. |
Заголовок запроса
Список заголовков запросов для API в этой статье.
Текст запроса
Недоступно
Состояние ответа
Помимо стандартного состояния HTTP в этой статье API может возвращать это состояние HTTP:
| Имя | Description |
|---|---|
| 410 — потеряно | Каждая ссылка на операцию активна для указанного количества времени, управляемого сервером. После истечения времени клиент должен отправить новый запрос. |
Полезные данные ответа
Полезные данные ответа API возвращают следующие атрибуты:
| Имя. | Необязательно | Description |
|---|---|---|
| createdDateTime | false | Время запроса. |
| lastActionDateTime | false | Время изменения состояния. |
| resourceLocation | true | URI полезных данных манифеста. |
| статус | false | Возможные значения и действия. |
| Значение | Действие клиента |
|---|---|
| notstarted | Выполните еще один вызов, чтобы проверить состояние после ожидания времени, указанного в заголовке Retry-After. |
| выполняется | Выполните еще один вызов, чтобы проверить состояние после ожидания времени, указанного в заголовке Retry-After. |
| Выполнено | Окончательное состояние операции, указывающее, что данные готовы. Извлеките полезные данные манифеста с помощью URI, указанного в resourceLocation. |
| ошибка | Состояние терминала, указывающее на постоянный сбой. Перезапустите операцию. |
Для атрибута ошибки:
| Имя. | Необязательно | Description |
|---|---|---|
| error | true | Сведения об ошибке, предоставленные в формате JSON, если состояние операции завершилось сбоем. |
| Имя. | Необязательно | Description |
|---|---|---|
| message | false | Подробно описывает ошибку |
| кодом | false | Указывает тип ошибки, которая произошла |
Запрос API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Ответ API
Ответ предлагает ждать 10 секунд до повторных попыток при обработке данных.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
Запрос API
(через 10 секунд после предыдущего запроса)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Ответ API
API возвращает состояние "успешно" и универсальный код ресурса (URI) resourceLocation.
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Шаг 3. Получение полезных данных манифеста
Вызывающий объект отправляет запрос GET к URL-адресу манифеста, чтобы узнать больше о том, где хранятся данные выверки в БОЛЬШИХ двоичных объектах Azure.
Получение манифеста
Извлекает манифест с информацией о расположении хранилища Azure данных выверки.
Запрос API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Параметры запроса
| Имя | In | Обязательный | Тип | Description |
|---|---|---|---|---|
| manifestId | Путь | Истина | Строка | Идентификатор манифеста. |
Заголовок запроса
См. [список заголовков запросов для API] в этой статье.
Текст запроса
Недоступно
Состояние ответа
Помимо стандартного состояния HTTP API может возвращать это состояние HTTP:
| Имя | Description |
|---|---|
| 410 — потеряно | Каждая ссылка манифеста активна в течение указанного времени, управляемого сервером. После истечения времени клиент должен отправить новый запрос. |
Полезные данные ответа
Ответ API возвращает следующие атрибуты:
| Имя | Description |
|---|---|
| Версия | Версия схемы манифеста. |
| dataFormat | Формат файла данных выставления счетов. Возможные значения сжатыJSONLines: каждый большой двоичный объект является сжатым файлом, а данные в файле — в формате строк JSON. Чтобы получить доступ к данным, распаковите файл. |
| UTCCreatedDateTime | Время создания файла манифеста. |
| eTag | Версия данных манифеста. Изменение сведений о выставлении счетов создает новое значение eTag. |
| partnerTenantId | Идентификатор клиента партнера. |
| rootFolder | Корневой каталог файла. |
| rootFolderSAS | Маркер SAS для доступа к файлу. |
| partitionType | Это свойство делит данные. Если в заданной секции больше поддерживаемого числа, данные делятся на несколько файлов, соответствующих параметру partitionValue. По умолчанию системные секционируют данные на основе количества элементов строки в файле. Не устанавливайте фиксированное количество строк или размер файла в коде, так как принцип секционирования может измениться. |
| BLOBCount | Общее число файлов для этого идентификатора клиента партнера. |
| sizeInBytes | Всего байтов во всех файлах. |
| большие двоичные объекты | Массив JSON объектов "BLOB-объектов" с подробными сведениями обо всех файлах для идентификатора клиента партнера. |
| Объект BLOB-объектов | |
| Имя. | Имя BLOB-объекта. |
| sizeInBytes | Размер большого двоичного объекта в байтах. |
| partitionValue | Раздел, содержащий файл. Большая секция будет разделена на несколько файлов, каждая из которых имеет одно и то же значение partitionValue. |
Пример полезных данных манифеста
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
Шаг 4. Скачивание данных выверки использования из расположения хранилища
Получите маркер SAS и расположение хранилища BLOB-объектов из свойств rootFolderSAS и rootFolder, ответ API полезных данных манифеста. С помощью пакета SDK или средства служба хранилища Azure скачайте и распакуйте файл BLOB-объекта. Он находится в формате строк JSON .
Стандартные заголовки запросов API
Все API принимают следующие заголовки:
| Имя | Обязательный | Тип | Description |
|---|---|---|---|
| Авторизация | Истина | Строка | Маркер носителя авторизации. |
| ms-correlationid | False | Строка | Внутренний средство отслеживания запросов. Каждый запрос создает новый трекер (GUID). |
| ms-cv | False | Строка | Внутренний средство отслеживания запросов. |
| ms-requestid | False | Строка | Идентификатор идемпотентности запроса. |
Стандартные состояния ответа API
Ниже приведены состояния HTTP из ответа API:
| Имя | Description |
|---|---|
| 400 — недопустимый запрос | Отсутствуют или неверные данные. Сведения об ошибке включены в текст ответа. |
| 401 — не авторизовано | Вызывающий объект не проходит проверку подлинности и должен пройти проверку подлинности в службе API партнера перед первым вызовом. |
| 403. Запрещено | Вызывающий объект не авторизован для выполнения запроса. |
| 500 Internal Server Error (внутренняя ошибка сервера). | API или одна из его зависимостей не может выполнить запрос. Повторите попытку позже. |
| 404 Не найдено | Ресурс недоступен с входными параметрами. |
| 410 — потеряно | Время ожидания или истечения времени ожидания ссылки манифеста. Отправьте новый запрос. |
Атрибуты данных об использовании
Ответ API выставления счетов или необясченного использования с параметром "full" или "basic" запроса возвращает следующие атрибуты:
| Attribute | "полный" | "базовый" |
|---|---|---|
| PartnerId | yes | yes |
| PartnerName | yes | yes |
| CustomerId | yes | yes |
| CustomerName | yes | Да |
| CustomerDomainName | yes | no |
| CustomerCountry | yes | no |
| MpnId | yes | no |
| Tier2MpnId | yes | no |
| InvoiceNumber | yes | yes |
| ИД продукта | yes | yes |
| SkuId | yes | yes |
| AvailabilityId | yes | no |
| SkuName | yes | yes |
| НаименованиеПродукта | yes | no |
| PublisherName | yes | yes |
| PublisherId | yes | no |
| SubscriptionDescription | yes | no |
| SubscriptionId | yes | yes |
| ChargeStartDate | yes | yes |
| ChargeEndDate | yes | yes |
| UsageDate | yes | yes |
| MeterType | yes | no |
| MeterCategory | yes | no |
| MeterId | yes | no |
| MeterSubCategory | yes | no |
| MeterName | yes | no |
| MeterRegion | yes | no |
| Единица измерения | yes | yes |
| Расположение ресурса | yes | no |
| ConsumedService | yes | no |
| ResourceGroup | yes | no |
| ResourceURI | yes | yes |
| ChargeType | yes | yes |
| UnitPrice | yes | yes |
| Количество | yes | yes |
| UnitType | yes | no |
| BillingPreTaxTotal | yes | yes |
| BillingCurrency | yes | yes |
| ЦенаPreTaxTotal | yes | yes |
| PricingCurrency | yes | yes |
| ServiceInfo1 | yes | no |
| ServiceInfo2 | yes | no |
| Теги | yes | no |
| AdditionalInfo | yes | no |
| EffectiveUnitPrice | yes | yes |
| PCToBCExchangeRate | yes | yes |
| PCToBCExchangeRateDate | yes | no |
| Идентификатор прав | yes | yes |
| НазначениеDescription | yes | no |
| PartnerEarnedCreditPercentage | yes | no |
| CreditPercentage | yes | yes |
| CreditType | yes | yes |
| BenefitOrderID | yes | yes |
| BenefitID | yes | no |
| BenefitType | yes | yes |