課金対象および未請求の日単位の使用状況調整 API v2 (GA)

[アーティクル]
12/04/2024

適用対象: パートナーセンター (Azure Government または Azure China 21Vianet では使用できません)。

新しい非同期 API は、Azure BLOB を介して課金と調整のデータにすばやく効率的にアクセスする方法を提供します。接続を何時間も開いたままにしたり、2,000 行の項目をバッチ処理したりするのではなく、ワークフローを効率化し、サーバーの負荷を軽減し、データ処理時間を短縮することが可能となりました。

新しいコマースの毎日の使用状況の調整 API では、valet キー asynchronous request-reply パターンなどの高度な手法が使用されます。バレットキーパターンは、資格情報を共有せずにリソースへの安全なアクセスをサポートしますが、非同期の要求/応答パターンはシステム間の効率的な通信を可能にします。

これらの API には、すべての属性または日単位の使用状況調整データのサブセットにアクセスするために使用できる Shared Access Signature (SAS) トークンが用意されています。このトークンは、時間制限付きアクセス権を付与することでセキュリティを強化し、データアクセス許可の管理に柔軟性を提供します。

最適化された API を採用することで、少ない労力でより迅速に結果を導き出し、データアクセスを単純化し、全体的な効率を向上させることができます。これらのツールを活用して、ワークフローを合理化し、アクセス許可をより効果的に管理します。

Note

新しい API は、パートナーセンター API ホストでホストされていません。代わりに、MS Graph で見つけることができます Microsoft Graph API を使用してパートナーの課金データをエクスポートする - Microsoft Graph v1.0 |Microsoft Learn。これらの API にアクセスするには、次の詳細を参照してください。

現時点では、これらの API は MS Graph パブリックグローバルクラウドにのみ使用できます。 Azure Government または Azure China ではまだ使用できません。

アプリがパートナーの課金データにアクセスできるようにする

アプリがパートナーの課金データにアクセスできるようにするには、このリンクに従って、Microsoft Graph の認証と承認の基本について理解します。この手順は、アプリが必要なデータに安全にアクセスできるようにするために大変重要です。

PartnerBilling.Read.All アクセス許可を割り当てる

Azure portal または Microsoft Entra 管理センターを使用して、"PartnerBilling.Read.All" アクセス許可を割り当てます。これらの手順により、アプリがパートナーの課金データに必要なアクセス権を持っていることを確認します。

[アプリの登録] セクションの Microsoft Entra ホームページでアプリを登録します。
Microsoft Entra App ページに移動して、必要なアクセス許可を付与します。 [API のアクセス許可] セクションで、[アクセス許可 の追加] を選択し、PartnerBilling.Read.All スコープを選択します。

ベータ版と GA バージョンの違いを理解する

ベータ版を使用している場合は、一般提供 (GA) バージョンへの移行がスムーズで直感的である可能性があります。更新プログラムと機能強化を理解するために、ベータ版と GA バージョン比較することをお勧めします。これらの更新プログラムを理解すると、GA バージョンで使用できる新機能と機能強化を最大限に活用できます。

重要

新しいコマース毎日の評価使用量には、次の製品の料金は含まれません。

Azure 予約
Azure 節約プラン
Office
Dynamics
Microsoft Power Apps
永続的ソフトウェア
ソフトウェアサブスクリプション
Microsoft 以外またはマーケットプレースの SaaS 製品

API エンドポイントを理解して使用する

課金対象の 新しいコマース 毎日評価される使用状況の行項目を非同期的に取得できるように、2 つの主要な API エンドポイントが用意されています。この合理化されたガイドに従って、すぐに開始してください。

行項目エンドポイントを使用する

最初に、この API を使用して、毎日評価 利用明細項目 新しいコマースを取得します。要求を行うと、202 HTTP 状態と URL を含む場所ヘッダーが表示されます。成功状態とマニフェスト URL が取得されるまで、この URL を定期的にポーリングします。

操作状態エンドポイントを使用する

これらの手順に従うことで、請求書調整プロセスを効率的に管理できます。

この API を定期的に呼び出して、操作の状態を確認し続けます。データの準備ができていない場合、応答には、再試行するまでの待機時間を示す Retry-After ヘッダーが含まれます。操作が完了すると、使用状況データをダウンロードするためのストレージフォルダーリンクを含むマニフェストリソースが表示されます。応答によってファイルがセグメント化され、スループットが向上し、I/O 並列処理が可能になります。

調整データをダウンロードする

調整データをダウンロードする手順を示すシーケンス図を次に示します。

調整データをダウンロードする手順を示す図。

ユーザーアクションシーケンスに従う

新しいコマース の毎日評価された使用量の調整明細項目 を取得するためのユーザーが行うべき手順を次に示します。

リクエストを送信する
要求の状態を確認
Azure Blob Storage から日単位の使用状況調整項目をダウンロードする

要求を送信する

API エンドポイントに POST 要求を送信します。

1 日ごとの課金対象の使用状況の明細項目を取得する

現在 または最後のカレンダー月または請求期間 新しいコマース未請求の日単位の使用状況の明細項目を取得します。

Note

API またはパートナーセンターポータルを使用して、 非請求 日単位の使用明細項目にアクセスできます。データの正確性を確保するため、利用可能になるまでに最大 24 時間かかる場合があります。場所やメーターが使用状況を報告するタイミングによっては、さらに遅延が発生する可能性があります。

最初に、請求日単位の使用状況データの時間配信に優先順位を付けます。場合によって、最新の未請求の日単位の使用データは、前月の請求データが利用可能になるまで表示されないことがあります。請求データが送信されると、月初めからの、更新されたすべての未請求の使用データにアクセスできるようになります。

重要ポイント:

データが利用可能になるまで最大 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"

}

要求本文

Attribute	必須	タイプ	説明
attributeSet	いいえ	String	すべての属性に対して "full" を選択し、限定セットの場合は "basic" を選択します。指定しない場合、既定値は "full" です。このセクションの属性の一覧を確認してください。省略可。
billingPeriod	True	String	未請求の日単位の使用状況を取得するには、現在の請求期間の "current"、または前の請求期間の "last" (v1 API の "previous" と同じ) を使用します。必須。
currencyCode	True	String	パートナーの請求通貨コード。必須。

要求ヘッダー

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 状態で応答します。要求によっては、他のステータスに遭遇することもあります。これらの状態は、「 Standard API 応答の状態」セクションに記載されています。

コード	説明
202 - 承諾済み	要求が受け入れられました。要求の状態を確認するには、location ヘッダーに指定された URL を照会します。

請求日単位の使用状況の明細項目を取得する

新しいコマースを取得支払い済みの請求期間の請求書に対して毎日評価される使用状況の明細項目が課金されます。

API 要求

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

クエリパラメーター

該当なし

要求本文

Attribute	必須	タイプ	説明
invoiceld	True	String	各請求書の一意の識別子。必須。
attributeSet	いいえ	String	すべての属性に対して "full" を選択し、限定セットの場合は "basic" を選択します。指定しない場合、既定値は "full" です。このセクションの属性の一覧を確認してください。省略可。

要求ヘッダー

API の要求ヘッダー。詳細については、責任とサポートを参照してください。

API 応答

HTTP/1.1 202 Accepted
場所: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

API を使用すると、通常は HTTP 202 状態が返されます。要求に応じて返される可能性のあるその他の状態については、状態を参照してください。

コード	説明
202 - 承諾済み	要求が受け入れられました。要求の状態を確認するには、location ヘッダーに指定された URL を照会します。

要求の状態を確認する

要求の状態を追跡するには、"成功" または "失敗" を示す標準の状態コードである HTTP 200 応答を受け取っていることを確認します。成功した場合は、"resourceLocation" 属性にマニフェスト URL が指定されています。この属性は、必要な情報にアクセスするためのエンドポイントを提供します。

操作の状態を取得する

要求の状態を取得します。

API 要求

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

要求パラメーター

Name	に含める	必須	タイプ	説明
operationId	要求 URI	True	String	要求の状態を確認する一意の識別子。必須。

要求ヘッダー

API のヘッダーを要求するには、「責任とサポートを参照してください。

要求本文

該当なし。

応答の状態

Standard API 応答の状態に記載されている標準の HTTP 状態とは別に、API は次の HTTP 状態を返すこともできます。

コード	説明
410 - 消失しました	マニフェストリンクは、設定された時間が経過すると期限切れになります。マニフェストリンクをもう一度取得するには、新しい要求を送信します。

応答ペイロード

API 応答ペイロードには、次の属性が含まれています。

Attribute	必須	説明
id	True	各応答の一意の識別子。必須。
status	True	値とアクション: Required: notstarted: "Retry-After" ヘッダーの指定時間を待機してから、別の呼び出しを行って状態を確認します。 running: "Retry-After" ヘッダーの指定時間を待機してから、別の呼び出しを行って状態を確認します。 succeeded: データの準備ができました。 resourceLocation で指定された URI を使用してマニフェストペイロードを取得します。 failed: 操作は永続的に失敗しました。再起動します。
createdDateTime	True	要求が行われた時刻。必須。
lastActionDateTime	True	状態が最後に変更された時刻。必須。
resourceLocation	いいえ	マニフェストペイロードの URI。省略可。
エラー	いいえ	JSON 形式で提供されるエラーの詳細。省略可。含まれる属性: message: エラーの説明。 code: エラーの種類。

リソースの場所オブジェクト

Attribute	説明
id	マニフェストの一意識別子。
schemaVersion	マニフェストスキーマのバージョン。
dataFormat	課金データファイルの形式。 compressedJSON: 各 BLOB が、 JSON 行形式のデータを含む圧縮ファイルであるデータ形式。各 BLOB からデータを取得するには、データを展開します。
createdDateTime	マニフェストファイルが作成された日時。
eTag	マニフェストデータのバージョン。課金情報を変更すると、新しい値が生成されます。
partnerTenantId	パートナーのテナントの Microsoft Entra ID。
rootDirectory	ファイルのルートディレクトリ。
sasToken	ディレクトリのすべてのファイルを読み取る SAS (Shared Access Signature) トークン。
partitionType	"partitionValue"属性に基づいて、データを複数の BLOB に分割します。システムは、サポートされている数を超えるパーティションを分割します。既定では、データはファイル内の行項目の数に基づいてパーティション分割されます。変更の可能性があるため、項目数やファイルサイズのハードコーディングは避けてください。
blobCount	このパートナーテナント ID のファイルの合計数。
blobs	パートナーテナント ID のファイルの詳細を含む "BLOB" オブジェクトの JSON 配列。
BLOB オブジェクト	次の詳細を含むオブジェクト: name と partitionValue
name	BLOB の名前です。
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 は、"成功" 状態と "resourceLocation" の URI を返します。

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"

            }

        \]

    }

}

Azure Blob Storage から毎日評価される使用状況調整の行項目をダウンロードする

まず、Shared Access Signature (SAS) トークンと BLOB ストレージの場所を取得する必要があります。これらの詳細については、マニフェストペイロード API 応答の sasToken プロパティと rootDirectory プロパティを参照してください。次に、BLOB ファイルをダウンロードして解凍するには、Azure Storage SDK/ツールを使用します。 JSONLines 形式です。

ヒント

サンプルコードを確認してください。 Azure BLOB ファイルをダウンロードしてローカルデータベースに解凍する方法を示します。

標準の API 応答の状態を理解する

API 応答から次の HTTP 状態を受け取る場合があります。

コード	説明
400 - Bad Request	要求が見つからないか、正しくないデータが含まれています。エラーの詳細については、応答本文を確認してください。
401 - Unauthorized	最初の呼び出しを行う前に認証が必要です。パートナー API サービスで認証します。
403 - Forbidden	要求を行うために必要な承認がありません。
404 - 見つかりません	要求されたリソースは、指定された入力パラメーターでは使用できません。
410 - 消滅しました	マニフェストリンクが無効またはアクティブになっています。新しい要求を送信します。
500 - 内部サーバーエラー	API またはその依存関係は、現時点では要求を満たすことはできません。後でもう一度試してみてください。
5000 - 使用できるデータがありません	システムには、指定された入力パラメーターのデータがありません。

ベータ版と GA バージョンを比較する

ベータ版と一般公開 (GA) バージョンの違いについては、次の比較表を参照してください。現在ベータ版を使用している場合、GA バージョンへの移行は簡単で簡単です。

重要情報	Beta	一般公開
API ホストエンドポイント	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
HTTP メソッド	投稿	投稿
毎日評価されない使用状況 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 のクエリ文字列にパラメーターを含めます。たとえば、period パラメーターと currencyCode パラメーターを指定するには、要求 URL に `?period=current&currencyCode=usd` を追加します。	入力を提供するには、要求本文に JSON オブジェクトを含めます。 JSON には、次のプロパティが必要です。 * currencyCode: 課金通貨。たとえば、USD です。 * billingPeriod: 請求書の請求期間。たとえば、現在の値です。 currencyCode プロパティと billingPeriod プロパティを含む JSON オブジェクトの例を次に示します。`<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 に invoiceId を含めます。さらに、クエリ文字列に省略可能なフラグメントパラメーターを含め、属性の完全なセットを取得できます。たとえば、属性の完全なセットを取得するには、要求 URL に `?fragment=full` を追加します。	入力を提供するには、要求本文に JSON オブジェクトを含めます。 JSON には、次のプロパティが必要です。 * invoiceId: 請求書の一意識別子。たとえば、G00012345。 * attributeSet: 応答に含める必要がある属性 (full など)。 invoiceId プロパティと attributeSet プロパティを含む JSON オブジェクトの例を次に示します。 `{<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}`
マニフェストリソース	マニフェストリソースを取得するには、別の GET /manifests/{id} メソッドを使用します。	get /operations/{Id} メソッドを使用して、resourceLocation のマニフェストリソースにアクセスします。このメソッドでは、GET /manifests/{id} を個別に呼び出す必要がなくなるため、時間を節約できます。
マニフェストスキーマの変更
	"id": 使用できません	"id": マニフェストリソースの一意の識別子。
	"version": Available	"version": "schemaversion" に変更されました。
	"dataFormat": 使用可能	"dataFormat": 使用できます。
	"utcCretedDateTime": 使用可能	"utcCretedDateTime": "createdDateTime" に変更されました。
	"eTag": 使用可能	"eTag": 使用できます。
	"partnerTenantId": 使用可能	"partnerTenantId": 使用可能
	"rootFolder": 使用可能	"rootFolder": "rootDirectory" に変更されました。
	"rootFolderSAS": 使用可能	"rootFolderSAS": "sasToken" に変更されました。この更新プログラムは、ルートディレクトリパスのないトークンのみを提供します。ディレクトリを見つけるには、代わりに "rootDirectory" プロパティを使用します。
	"partitionType": 使用可能	"partitionType": 使用できます。
	"blobCount": 使用可能	"blobCount": 使用できます。
	"sizeInBytes": 使用可能	"sizeInBytes": 使用できません。
	"BLOB": 使用可能	"BLOB": 使用できます。
	"BLOB オブジェクト": 使用可能	"BLOB オブジェクト": 使用できます。
	"name": 使用可能	"name": 使用できます。
	"partitionValue": 使用可能	"partitionValue": 使用できます。

日単位の使用状況調整項目の属性を比較する

"full" または "basic" の属性セットについて、請求済みまたは未請求の使用状況調整 API によって返される属性を比較するには、次の表を参照してください。これらの属性とその意味の詳細については、毎日評価される使用状況調整ファイルのフィールドを参照してください。

Attribute	完全	基本
PartnerId	はい	はい
PartnerName	はい	はい
CustomerId	はい	はい
CustomerName	はい	はい
CustomerDomainName	はい	いいえ
CustomerCountry	はい	いいえ
MpnId	はい	いいえ
Tier2MpnId	はい	いいえ
InvoiceNumber	はい	はい
製品 ID	はい	はい
SkuId	はい	はい
AvailabilityId	はい	いいえ
SkuName	はい	はい
ProductName	はい	いいえ
発行元	はい	はい
PublisherId	はい	いいえ
SubscriptionDescription	はい	いいえ
SubscriptionId	はい	はい
ChargeStartDate	はい	はい
ChargeEndDate	はい	はい
UsageDate	はい	はい
MeterType	はい	いいえ
測定カテゴリ（MeterCategory）	はい	いいえ
MeterId	はい	いいえ
測定サブカテゴリ（MeterSubCategory）	はい	いいえ
MeterName	はい	いいえ
MeterRegion	はい	いいえ
出荷単位	はい	はい
ResourceLocation	はい	いいえ
ConsumedService	はい	いいえ
ResourceGroup	はい	いいえ
ResourceURI	はい	はい
料金の種類（ChargeType）	はい	はい
UnitPrice	はい	はい
数量（Quantity）	はい	はい
UnitType	はい	いいえ
BillingPreTaxTotal	はい	はい
請求通貨（BillingCurrency）	はい	はい
PricingPreTaxTotal	はい	はい
PricingCurrency	はい	はい
ServiceInfo1	はい	いいえ
ServiceInfo2	はい	いいえ
Tags	はい	いいえ
AdditionalInfo	はい	いいえ
EffectiveUnitPrice	はい	はい
PCToBCExchangeRate	はい	はい
PCToBCExchangeRateDate	はい	いいえ
EntitlementID	はい	はい
EntitlementDescription	はい	いいえ
PartnerEarnedCreditPercentage	はい	いいえ
CreditPercentage	はい	はい
CreditType	はい	はい
BenefitOrderID	はい	はい
BenefitID	はい	いいえ
BenefitType	はい	はい

重要

API v1 から v2 に移行する際は、次の変更に留意してください。

各属性名は、ファイルとの一貫性を維持し、読みやすさを向上させるために、大文字 で始まるようになりました。
unitOfMeasure が Unit に更新されます。その意味と値は変更せず、属性名を簡略化しています。
resellerMpnId がTier2MpnIdになりました。意味と値は同じです。
rateOfPartnerEarnedCredit は PartnerEarnedCreditPercentage に更新されます。新しい名前と値では、小数ではなくパーセンテージで示されることで、理解しやすくなりました。たとえば、0.15 は 15% になりました。
rateOfCredit がCreditPercentage になりました。名前と値の両方が、より明確に理解できるように変更されました。たとえば、1.00 は 100% になりました。

これらの変更により、API はより直感的で使いやすくなっていると考えられます。

サンプルコードを取得する

この API を使用するには、C# サンプルコードを含む次のリンクを参照してください。

パートナーセンター API のサンプル: 課金の調整データを取得する。

次の方法で共有

課金対象および未請求の日単位の使用状況調整 API v2 (GA)

アプリがパートナーの課金データにアクセスできるようにする

PartnerBilling.Read.All アクセス許可を割り当てる

ベータ版と GA バージョンの違いを理解する

API エンドポイントを理解して使用する

行項目エンドポイントを使用する

操作状態エンドポイントを使用する

調整データをダウンロードする

ユーザー アクション シーケンスに従う

要求を送信する

1 日ごとの課金対象の使用状況の明細項目を取得する

API 要求

要求本文

要求ヘッダー

API 応答

請求日単位の使用状況の明細項目を取得する

API 要求

要求本文

要求ヘッダー

API 応答

要求の状態を確認する

操作の状態を取得する

API 要求

要求パラメーター

要求ヘッダー

要求本文

応答の状態

応答ペイロード

リソースの場所オブジェクト

API 要求

API 応答

API 要求

API 応答

Azure Blob Storage から毎日評価される使用状況調整の行項目をダウンロードする

標準の API 応答の状態を理解する

ベータ版と GA バージョンを比較する

日単位の使用状況調整項目の属性を比較する

サンプル コードを取得する

フィードバック

その他のリソース

ユーザーアクションシーケンスに従う

サンプルコードを取得する