Получение позиций из счета за неоплачиваемое потребление продуктов на коммерческой платформе

Статья
02/03/2025

Примечание.

Ключевые даты и сценарии миграции

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

сценарии A: текущие или предыдущие периоды выставления счетов (до 21 апреля 2025 г.):

Продолжить использование этого API до 21 апреля 2025 г., если вы еще не перешли в общедоступную версию API версии 2.

сценарий B: текущие или предыдущие периоды выставления счетов (после 21 апреля 2025 г.):

Перейти на API версии 2 GA для получения данных по всем будущим периодам выставления счетов.

Переход от API версии 1 к API версии 2 включает подробное планирование и точное выполнение. Чтобы обеспечить плавный переход к новому API, посетите: API сверки тарифицированного и нетарифицированного ежедневного использования версии 2 (GA).

Мы ценим ваше внимание и привержены поддержке ваших дальнейших успехов с нашими API выставления счетов.

Как получить набор данных с невыставленными деталями позиций коммерческого потребления.

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

Внимание

Данные о ежедневном использовании не включают расходы на эти продукты:

Резервирование Azure
Экономичный план Azure
Офис
Динамика
Microsoft Power Apps
Программное обеспечение с бессрочной лицензией
Подписка на программное обеспечение
Продукт SaaS, отличный от Майкрософт или Marketplace

Примечание.

Вы можете получить доступ к невыставленным на счёт ежедневным тарифицированным строкам использования с помощью API или портала Центра партнеров. Для обеспечения точности данных дайте до 24 часов на ожидание доступности. В зависимости от расположения и времени, когда счетчики сообщают об использовании, могут возникнуть дополнительные задержки.

В первую очередь мы обеспечиваем своевременную доставку данных об учтенном ежедневном использовании по счетам. Иногда самые недавние нефактурированные ежедневные данные по тарифам могут не отображаться, пока не станут доступны счета за предыдущий месяц. После получения выставленных данных счетов вы сможете получить доступ ко всем обновленным необработанным данным об использовании с начала месяца.

Ключевые моменты:

Подождите до 24 часов для доступности данных.
В зависимости от вашего местоположения и времени отчетности счетчика могут возникнуть дополнительные задержки.
Оплаченные данные об использовании с суточным тарифом имеют приоритет перед неоплаченными данными.

Ваше понимание и терпение ценятся, так как мы стремимся обеспечить наиболее точную и своевременную информацию.

Предварительные требования

Учетные данные, как описано в аутентификации в Центре партнеров. Этот сценарий поддерживает аутентификацию как с автономными учетными данными приложения, так и с учетными данными приложения и пользователя.

C#

Чтобы получить позиции в указанном счете:

Вызовите метод ById, чтобы получить интерфейс для операций с указанным счетом.
Вызовите метод Get или GetAsync, чтобы получить объект счета.

Объект счета содержит все сведения для указанного счета. Поставщик определяет источник необязаемых сведений (например, OneTime). Объект InvoiceLineItemType указывает тип (например, UsageLineItem).

В следующем примере кода используется цикл foreach для обработки коллекции InvoiceLineItems. Для каждого InvoiceLineItemType извлекается отдельная коллекция строковых элементов.

Чтобы получить коллекцию позиций, которая соответствует экземпляру InvoiceDetail:

Передайте экземпляру параметры BillingProvider и InvoiceLineItemType методу By.
Вызовите метод Get или GetAsync, чтобы получить связанные элементы строки.
Создайте перечислитель для обхода коллекции, как показано в следующем примере.

// IAggregatePartner partnerOperations;
// string curencyCode;
// string period;
// int pageMaxSizeReconLineItems = 2000;

// all the operations executed on this partner operation instance will share the same correlation Id but will differ in request Id
IPartner scopedPartnerOperations = partnerOperations.With(RequestContextFactory.Instance.Create(Guid.NewGuid()));

var seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById("unbilled").By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Get();

var fetchNext = true;

ConsoleKeyInfo keyInfo;

var itemNumber = 1;
while (fetchNext)
{
    Console.Out.WriteLine("\tLine items count: " + seekBasedResourceCollection.Items.Count());

    seekBasedResourceCollection.Items.ToList().ForEach(item =>
    {
        // Instance of type DailyRatedUsageLineItem
        if (item is DailyRatedUsageLineItem)
        {
            Type t = typeof(DailyRatedUsageLineItem);
            PropertyInfo[] properties = t.GetProperties();

            foreach (PropertyInfo property in properties)
            {
                // Insert code here to work with the line item properties
            }
        }
        itemNumber++;
    });

    Console.Out.WriteLine("\tPress any key to fetch next data. Press the Escape (Esc) key to quit: \n");
    keyInfo = Console.ReadKey();

    if (keyInfo.Key == ConsoleKey.Escape)
    {
        break;
    }

    fetchNext = !string.IsNullOrWhiteSpace(seekBasedResourceCollection.ContinuationToken);

    if (fetchNext)
    {
        if (seekBasedResourceCollection.Links.Next.Headers != null && seekBasedResourceCollection.Links.Next.Headers.Any())
        {
            seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById("unbilled").By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Seek(seekBasedResourceCollection.ContinuationToken, SeekOperation.Next);
        }
    }
}

Аналогичный пример см. в следующем примере:

Пример: Тестовое приложение для консоли
Проект: примеры пакета SDK центра партнеров
Класс: GetUnBilledConsumptionReconLineItemsPaging.cs

Запрос REST

Синтаксис запроса

В зависимости от варианта использования можно использовать следующие синтаксисы для запроса REST. Дополнительные сведения см. в описаниях каждого синтаксиса.

Способ	URI запроса	Описание варианта использования синтаксиса
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period} HTTP/1.1	Используйте этот синтаксис, чтобы вернуть полный список каждого элемента строки для данного счета.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period}&size={size} HTTP/1.1	Используйте этот синтаксис для больших счетов. Используйте этот синтаксис с заданным размером и нулевым смещением для возврата постраничного списка элементов строки.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period}&size={size}&seekOperation=Next	Используйте этот синтаксис, чтобы получить следующую страницу позиций выверки с помощью `seekOperation = "Next"`.

Параметры универсального кода ресурса (URI)

При создании запроса используйте следующие параметры URI и запроса.

Имя.	Тип	Обязательно	Описание
поставщик	строка	Да	Поставщик: OneTime.
тип позиции счета-фактуры	строка	Да	Тип сведений о счете: "UsageLineItems", "UsageLineItems".
код валюты	строка	Да	Код валюты для необнаруженных элементов строки.
период	строка	Да	Период необязательного повторного согласования (например, текущий, предыдущий). Предположим, что вам нужно запросить невыставленные данные об использовании за период выставления счетов (01.01.2020 – 31.01.2020) в январе, выберите период как "Current," иначе "Previous."
размер	номер	Нет	Максимальное количество возвращаемых элементов. Размер по умолчанию — 2000.
операция поиска	строка	Нет	Установите `seekOperation=Next` для получения следующей страницы позиций выверки.

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

Дополнительную информацию можно найти в заголовках REST Центра партнеров.

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

Нет.

Ответ REST

При успешном выполнении ответ содержит коллекцию сведений о элементе строки.

Для элемента строки ChargeType значение Purchase сопоставляется с New, а значение Refund — с Cancel.

Коды успешного ответа и ошибок

Каждый ответ содержит код состояния HTTP, указывающий на успешность или сбой, а также другие сведения об отладке. Используйте средство трассировки сети для чтения этого кода, типа ошибки и других параметров. Для получения полного списка см. Коды ошибок REST в Центре партнеров.

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

Пример запроса-ответа 1

Следующие сведения относятся к этому примеру:

Поставщик: OneTime
InvoiceLineItemType: UsageLineItems
Период: предыдущий

Пример запроса 1

GET https://api.partnercenter.microsoft.com/v1//invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com

Внимание

По состоянию на июнь 2023 г. последняя версия пакета SDK для .NET для Центра партнеров 3.4.0 теперь архивируется. Вы можете скачать выпуск SDK с GitHub вместе с файлом readme, который содержит полезную информацию.

Партнерам рекомендуется продолжать использовать REST API Центра партнеров.

Пример ответа 1

HTTP/1.1 200 OK
Content-Length: 2484
Content-Type: application/json; charset=utf-8
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
MS-CV: bpqyomePDUqrSSYC.0
MS-ServerId: 202010406
Date: Wed, 20 Feb 2019 19:59:27 GMT

{
    "totalCount": 2,
    "items": [
        {
            "partnerId": "00083575-bbd0-54de-b2ad-0f5b0e927d71",
            "partnerName": "MTBC",
            "customerId": "",
            "customerName": "",
            "customerDomainName": "",
            "invoiceNumber": "",
            "productId": "",
            "skuId": "",
            "availabilityId": "",
            "skuName": "VM-Series Next-Generation Firewall (Bundle 2 PAYG)",
            "productName": "VM-Series Next Generation Firewall",
            "publisherName": "Test Alto Networks, Inc.",
            "publisherId": "",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "subscriptionDescription": "Pay-As-You-Go",
            "chargeStartDate": "2019-01-01T00:00:00Z",
            "chargeEndDate": "2019-02-01T00:00:00Z",
            "usageDate": "2019-01-01T00:00:00Z",
            "meterType": "1 Compute Hour - 4core",
            "meterCategory": "Virtual Machine Licenses",
            "meterId": "4core",
            "meterSubCategory": "VM-Series Next Generation Firewall",
            "meterName": "VM-Series Next Generation Firewall - VM-Series Next-Generation Firewall (Bundle 2 PAYG) - 4 Core Hours",
            "meterRegion": "",
            "unitOfMeasure": "1 Hour",
            "resourceLocation": "EASTUS",
            "consumedService": "Microsoft.Compute",
            "resourceGroup": "ECH-PAN-RG",
            "resourceUri": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ECH-PAN-RG/providers/Microsoft.Compute/virtualMachines/echpanfw",
            "tags": "",
            "additionalInfo": "{  \"ImageType\": null,  \"ServiceType\": \"Standard_D3_v2\",  \"VMName\": null,  \"VMProperties\": null,  \"UsageType\": \"ComputeHR_SW\"}",
            "serviceInfo1": "",
            "serviceInfo2": "",
            "customerCountry": "",
            "mpnId": "1234567",
            "resellerMpnId": "",
            "chargeType": "",
            "unitPrice": 1.2799888920023,
            "quantity": 24.0,
            "unitType": "",
            "billingPreTaxTotal": 30.7197334080551,
            "billingCurrency": "USD",
            "pricingPreTaxTotal": 30.7197334080551,
            "pricingCurrency": "USD",
            "entitlementId": "3f47bcf1-965d-40a1-a2bc-3d5db3653250",
            "entitlementDescription": "Partner Subscription",
            "pcToBCExchangeRate": 1,
            "pcToBCExchangeRateDate": "2019-08-01T00:00:00Z",
            "effectiveUnitPrice": 0,
            "rateOfPartnerEarnedCredit": 0,
            "rateOfCredit": 0,
            "creditType": "Credit Not Applied",
            "invoiceLineItemType": "usage_line_items",
            "billingProvider": "marketplace",
        "benefitOrderId": "5ea053d6-4a0d-46ef-bc82-15065b475d01",
        "benefitId": "28ddab06-2c5b-479e-88bb-7b7bfda4e7fd",
        "benefitType": "SavingsPlan",
            "attributes": {
                "objectType": "DailyRatedUsageLineItem"
            }
         },
         {
            "partnerId": "00083575-bbd0-54de-b2ad-0f5b0e927d71",
            "partnerName": "MTBC",
            "customerId": "",
            "customerName": "",
            "customerDomainName": "",
            "invoiceNumber": "",
            "productId": "",
            "skuId": "",
            "availabilityId": "",
            "skuName": "VM-Series Next-Generation Firewall (Bundle 2 PAYG)",
            "productName": "VM-Series Next Generation Firewall",
            "publisherName": "Test Alto Networks, Inc.",
            "publisherId": "",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "subscriptionDescription": "Pay-As-You-Go",
            "chargeStartDate": "2019-01-01T00:00:00Z",
            "chargeEndDate": "2019-02-01T00:00:00Z",
            "usageDate": "2019-01-02T00:00:00Z",
            "meterType": "1 Compute Hour - 4core",
            "meterCategory": "Virtual Machine Licenses",
            "meterId": "4core",
            "meterSubCategory": "VM-Series Next Generation Firewall",
            "meterName": "VM-Series Next Generation Firewall - VM-Series Next-Generation Firewall (Bundle 2 PAYG) - 4 Core Hours",
            "meterRegion": "",
            "unitOfMeasure": "1 Hour",
            "resourceLocation": "EASTUS",
            "consumedService": "Microsoft.Compute",
            "resourceGroup": "ECH-PAN-RG",
            "resourceUri": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ECH-PAN-RG/providers/Microsoft.Compute/virtualMachines/echpanfw",
            "tags": "",
            "additionalInfo": "{  \"ImageType\": null,  \"ServiceType\": \"Standard_D3_v2\",  \"VMName\": null,  \"VMProperties\": null,  \"UsageType\": \"ComputeHR_SW\"}",
            "serviceInfo1": "",
            "serviceInfo2": "",
            "customerCountry": "",
            "mpnId": "1234567",
            "resellerMpnId": "",
            "chargeType": "",
            "unitPrice": 1.2799888920023,
            "quantity": 24.0,
            "unitType": "",
            "billingPreTaxTotal": 30.7197334080551,
            "billingCurrency": "USD",
            "pricingPreTaxTotal": 30.7197334080551,
            "pricingCurrency": "USD",
            "entitlementId": "31cdf47f-b249-4edd-9319-637862d12345",
            "entitlementDescription": "Partner Subscription",
            "pcToBCExchangeRate": 1,
            "pcToBCExchangeRateDate": "2019-08-01T00:00:00Z",
            "effectiveUnitPrice": 0,
            "rateOfPartnerEarnedCredit": 0,
            "rateOfCredit": 1,
            "creditType": "Azure Credit Applied",
            "invoiceLineItemTypce": "usage_line_items",
            "billingProvider": "marketplace",
        "benefitOrderId": "",
            "benefitId": "",
            "benefitType": "Charge",
            "attributes": {
                "objectType": "DailyRatedUsageLineItem"
            }
        }
    ],
    "links": {
        "self": {
            "uri": "/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000",
            "method": "GET",
            "headers": []
        },
        "next": {
            "uri": "/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000&seekOperation=Next",
            "method": "GET",
            "headers": [
                {
                    "key": "MS-ContinuationToken",
                    "value": "AQAAAA=="
                }
            ]
        }
    },
    "attributes": {
        "objectType": "Collection"
    }
}

Пример ответа на запрос 2