Выставленные счета и неоплачиваемые ежедневные оценки API выверки использования версии 2 (GA)
Область применения: Центр партнеров (недоступно в Azure для государственных организаций или Azure China 21Vianet.)
Наш новый асинхронный API предлагает более быстрый и эффективный способ доступа к данным выставления счетов и выверки через большие двоичные объекты Azure. Вместо того, чтобы держать подключение открытым в течение нескольких часов или обрабатывать пакеты из 2000 элементов строки, теперь можно упростить рабочий процесс.
Новые API-интерфейсы выверки использования ежедневной коммерции используют расширенные методы, такие как ключ valet и асинхронные шаблоны ответа на запросы. Эти API предоставляют маркер подписанного URL-адреса (SAS), который можно использовать для доступа ко всем атрибутам или подмножества ежедневных данных сверки использования.
Наши API используют оптимизированные методы для повышения эффективности, чтобы добиться более быстрых результатов с меньшими усилиями. Обнимайте эти API, чтобы упростить доступ к данным и повысить общую эффективность.
Примечание.
Новые API не размещаются на узле API Центра партнеров. Вместо этого вы можете найти их в MS Graph на странице "Использование API Microsoft Graph для экспорта данных о выставлении счетов партнеров " Microsoft Graph версии 1.0 | Microsoft Learn. Чтобы получить доступ к этим API, ознакомьтесь со следующими сведениями.
Эти API можно использовать только для общедоступного или глобального облака MS Graph. Они пока недоступны для Azure для государственных организаций или Azure China 21Vianet.
Внимание
Чтобы разрешить приложению доступ к данным о выставлении счетов партнера, следуйте этой ссылке и ознакомьтесь с основами проверки подлинности и авторизации для Microsoft Graph.
Вы можете назначить разрешение PartnerBilling.Read.All с помощью портал Azure или Центра администрирования Entra. Это делается следующим образом:
- Зарегистрируйте приложение на домашней странице Microsoft Entra в разделе Регистрация приложений.
- Чтобы предоставить необходимое разрешение, перейдите на страницу приложения Microsoft Entra в разделе разрешений API. Выберите "Добавить разрешение" и выберите область "PartnerBilling.Read.All".
Выполнив эти действия, вы убедитесь, что ваше приложение имеет необходимый доступ к данным о выставлении счетов партнера.
Примечание.
Если вы использовали бета-версию, скорее всего, вы найдете переход на общедоступную и интуитивно понятную версию. Чтобы понять обновления и улучшения, рекомендуется сравнить бета-версии и версии общедоступной версии.
Внимание
Новая коммерческая ежедневная оценка использования не включает расходы на эти продукты:
- Резервирование Azure
- Экономичный план Azure
- Office
- Dynamics
- Microsoft Power Apps
- Программное обеспечение с бессрочной лицензией
- Подписка на программное обеспечение
- Продукт SaaS, отличный от Майкрософт или Marketplace
Обзор API
Для асинхронного получения выставленных счетов за новую коммерческую торговлю ежедневно оцененных элементов линии использования мы предлагаем две ключевые конечные точки API. Ниже приведено упрощенное руководство по началу работы:
Конечная точка элемента строки использования
Во-первых, используйте этот API для получения новых элементов линии использования ежедневной коммерческой торговли . При выполнении запроса вы получаете состояние HTTP 202 и заголовок расположения с URL-адресом. Регулярно опросите этот URL-адрес, пока не получите состояние успешного выполнения и URL-адрес манифеста.
Конечная точка состояния операции
Затем продолжайте проверять состояние операции, вызывая этот API через регулярные интервалы. Если данные не готовы, ответ включает заголовок Retry-After , указывающий, как долго ждать, прежде чем повторить попытку. После завершения операции вы получите ресурс манифеста со ссылкой на папку хранилища, чтобы скачать данные об использовании. Ответ сегментирует файлы, чтобы повысить пропускную способность и разрешить параллелизм ввода-вывода.
Выполнив следующие действия, вы можете эффективно управлять процессом выверки счетов.
Схема последовательностей
Ниже приведена схема последовательности, на которую показано, как скачать данные выверки.
Последовательность действий пользователя
Чтобы получить новые элементы линии выверки использования ежедневной коммерческой торговли , выполните следующие действия.
Шаг 1. Отправка запроса
Отправьте запрос POST в конечную точку API.
Получение необясченных ежедневных строк использования
Получение новых элементов линии ежедневного использования для текущего или последнего календарного месяца или периода выставления счетов.
Примечание.
Вы можете получить доступ к неоплачиваемой ежедневной строке использования с помощью API или портала Центра партнеров. Чтобы обеспечить точную информацию, до 24 часов для доступности. В зависимости от расположения и времени, когда счетчики сообщают об использовании, могут возникнуть дополнительные задержки.
Сначала мы ставим приоритеты по доставке оплачиваемых ежедневных данных об использовании. Иногда вы можете не видеть последние необнаруженные данные о ежедневном использовании, пока данные о выставлении счетов за предыдущий месяц не будут доступны. Получив данные о выставлении счетов, вы можете получить все обновленные необновенные данные об использовании с начала месяца.
Ваше понимание и терпение ценятся, так как мы стремимся обеспечить наиболее точную и своевременную информацию.
Запрос API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Accept: application/json
Content-Type: application/json
{
"currencyCode": "USD",
"billingPeriod": "current",
"attributeSet": "basic"
}
Текст запроса
Заголовки запросов
Чтобы запросить заголовки API, см. сведения о надежности и поддержке.
Ответ 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-адрес, указанный в заголовке расположения. |
Получение оплачиваемых ежедневных строк использования
Получение новых выставленных счетов за ежедневное выставление счетов за выставление счетов за закрытый период выставления счетов.
Запрос API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Параметры запроса
Н/П
Текст запроса
Заголовок запроса
Заголовок запроса для API. Дополнительные сведения см. в статье о надежности и поддержке.
Ответ API
Принято HTTP/1.1 202
Расположение: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
При использовании API обычно возвращается состояние HTTP 202. Сведения о других возможных состояниях на основе запросов см. в разделе "Состояния".
| Код | Описание |
|---|---|
| 202 — принято | Ваш запрос был принят. Чтобы проверить состояние запроса, запросите URL-адрес, указанный в заголовке расположения. |
Шаг 2. Проверка состояния запроса
Чтобы отслеживать состояние запроса, убедитесь, что вы получите ответ HTTP 200, указывающий на "успешно" или "неудачно". В случае успешного выполнения вы найдете URL-адрес манифеста в атрибуте resourceLocation. Этот атрибут предоставляет конечную точку для доступа к необходимым сведениям.
Получение состояния операции
Извлекает состояние запроса.
Запрос API
Параметры запроса
| Имя. | Включение в | Обязательное поле | Type | Описание |
|---|---|---|---|---|
| operationId | URI запроса | Истина | Строка | Уникальный идентификатор для проверки состояния запроса. Необходимые. |
Заголовок запроса
Чтобы запросить заголовки API, см. сведения о надежности и поддержке.
Текст запроса
Недоступно
Состояние ответа
Помимо стандартных состояний 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 | Идентификатор Microsoft Entra клиента партнера. |
| rootDirectory | Корневой каталог файла. |
| sasToken | Маркер SAS (подписанный URL-адресом), позволяющий считывать все файлы в каталоге. |
| partitionType | Делит данные на несколько больших двоичных объектов на основе атрибута partitionValue . Система разделяет секции, превышающие поддерживаемую цифру. По умолчанию данные секционируются на основе количества элементов строки в файле. Не устанавливайте фиксированное количество строк или размер файла в коде, так как эти значения могут измениться. |
| BLOBCount | Общее количество файлов для этого идентификатора клиента партнера. |
| большие двоичные объекты | Массив JSON объектов "BLOB-объектов", содержащий сведения о файле для идентификатора клиента партнера. |
| большой двоичный объект | Объект, содержащий следующие сведения: имя и 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:
| Код | Description |
|---|---|
| 400 — недопустимый запрос | Запрос отсутствует или содержит неверные данные. Проверьте текст ответа для получения сведений об ошибке. |
| 401 — не авторизовано; | Перед первым вызовом требуется проверка подлинности. Проверка подлинности с помощью службы API партнера. |
| 403 — запрещено; | У вас нет необходимой авторизации для выполнения запроса. |
| 404 — не найден | Запрошенные ресурсы недоступны с предоставленными входными параметрами. |
| 410 – Ушло | Ссылка манифеста больше не действительна или активна. Отправьте новый запрос. |
| 500 — внутренняя ошибка сервера | API или его зависимости не могут выполнять запрос прямо сейчас. Повторите попытку позже. |
| 5000 — нет доступных данных | Система не имеет данных для предоставленных входных параметров. |
Сравнение версий бета-версии и общедоступной версии
Ознакомьтесь с таблицей сравнения, чтобы увидеть различия между бета-версией и общедоступной версией. Если вы используете бета-версию, переход на общедоступную версию прост и прост.
| Важная информация | Бета-версия | Общедоступная версия |
|---|---|---|
| Конечная точка узла API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| Метод HTTP | POST | POST |
| Необилизованная конечная точка API ежедневного использования | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Входные параметры для неоплачиваемого API ежедневного использования | Чтобы указать параметры в запросе API, включите их в строку запроса URL-адреса запроса. Например, чтобы указать параметры периода и currencyCode, добавьте ?period=current¤cyCode=usd его к URL-адресу запроса. |
Чтобы предоставить входные данные, включите объект JSON в текст запроса. Код JSON должен иметь следующие свойства: * currencyCode: ваша валюта выставления счетов. Например, USD. * billingPeriod: период выставления счетов. Например, текущий. Ниже приведен пример объекта JSON, включающего свойства currencyCode и billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Конечная точка API использования с выставлением счетов | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Входные параметры для оплачиваемого API ежедневного использования | Чтобы указать параметры в запросе API, добавьте идентификатор счета в URL-адрес запроса. Кроме того, можно включить необязательный параметр фрагмента в строку запроса, чтобы получить полный набор атрибутов. Например, чтобы получить полный набор атрибутов, добавьте ?fragment=full его к URL-адресу запроса. |
Чтобы предоставить входные данные, включите объект JSON в текст запроса. Код JSON должен иметь следующие свойства: * invoiceId: уникальный идентификатор счета. Например, G00012345. * attributeSet: атрибуты, которые должны находиться в ответе, например полные. Ниже приведен пример объекта JSON, включающего свойства invoiceId и attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Ресурс манифеста | Используйте отдельный метод GET /manifests/{id}, чтобы получить ресурс манифеста. | Используйте метод GET /operations/{Id} для доступа к ресурсу манифеста в resourceLocation. Этот метод экономит время, устраняя необходимость отдельного вызова GET /manifests/{id}. |
| Изменения схемы манифеста | ||
| "id": недоступно | "id": уникальный идентификатор ресурса манифеста. | |
| "версия": доступно | "версия": изменено на "schemaversion". | |
| DataFormat:Available | DataFormat:Available. | |
| "utcCretedDateTime": доступно | UTCCretedDateTime: изменено на "createdDateTime". | |
| "eTag": доступно | "eTag": доступно. | |
| "partnerTenantId": доступно | "partnerTenantId": доступно | |
| "rootFolder": Доступно | RootFolder: изменено на rootDirectory. | |
| "rootFolderSAS": доступно | RootFolderSAS: изменено на sasToken. Это обновление предоставляет только маркер без пути корневого каталога. Чтобы найти каталог, используйте вместо этого свойство rootDirectory. | |
| PartitionType: Available | PartitionType: Доступно. | |
| "BLOBCount": Доступно | "BLOBCount": доступно. | |
| "sizeInBytes": доступно | "sizeInBytes": недоступно. | |
| "Большие двоичные объекты": доступно | "Большие двоичные объекты": доступно. | |
| "Объект BLOB-объектов": Доступно | "Объект BLOB-объектов": доступно. | |
| "name": Available | "name": Доступно. | |
| PartitionValue: Доступно | "partitionValue": доступно. |
Атрибуты элементов линии выверки ежедневного оценки использования
Чтобы сравнить атрибуты, возвращаемые API выверки выставленного счета для наборов атрибутов full или basic, см. в следующей таблице. Дополнительные сведения об этих атрибутах см. в этой документации.
| Атрибут | Полностью | Базовая |
|---|---|---|
| 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 |
Внимание
Запишите эти изменения при переходе из API версии 1 из версии 2.
Теперь каждое имя атрибута начинается с прописной буквы .
unitOfMeasure обновляется до Unit. Его значение и значение остаются неизменными.
resellerMpnId теперь имеет уровень 2MpnId. Значение и значение совпадают.
rateOfPartnerEarnedCredit обновляется до PartnerEarnedCreditPercentage. Новое имя и значение теперь отражают процент вместо дроби. Например, 0,15 теперь составляет 15 %.
rateOfCredit теперь CreditPercentage. Имя и значение изменились. Например, 1,00 теперь составляет 100 %.
Мы считаем, что эти изменения делают API более интуитивно понятными и удобными для использования.
Пример кода
Чтобы использовать этот API, см. следующую ссылку, включающую пример кода C#.
Примеры API Центра партнеров: получение данных о рекогносцировке выставления счетов.