請求と調整 API v2 (ベータ)

適用対象: パートナー センター | 21Vianet が運営するパートナー センター | Microsoft Cloud for US Government のパートナー センター

これらの API を使用して、毎日評価された課金対象の使用状況データを非同期的に取得します。

Note

この API は、2024 年 6 月 30 日以降、毎日の課金対象の使用状況が機能しなくなります。 使用するバージョンとタイミングを決定するには、次の詳細を参照してください。

• v2 GA に切り替えない限り、この API を 2024 年 6 月 30 日まで使用して、2022 年 9 月から 2024 年 6 月までの請求期間に対して作成された請求書に対して、毎日評価される使用量明細を取得します。
• 2024 年 6 月 30 日以降は API v2 GA のみを使用して、2022 年 9 月から請求期間に作成された請求書に対して毎日評価される使用量明細を取得します。

この API は、2024 年 6 月 30 日以降は、毎日評価されない使用状況で動作しなくなります。 使用するバージョンとタイミングを決定するには、次の詳細を参照してください。

• v2 GA に切り替えた場合を除き、この API を 2024 年 6 月 30 日まで使用して、 現在および以前の請求期間の日単位の評価されない使用明細を取得します。
• 2024 年 6 月 30 日以降は API v2 GA のみを 使用して、 現在および以前の請求について、毎日評価されない使用状況の明細項目を取得します。

新しい v2 GA API への移行の準備を開始するには、次のリンクを参照してください。

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

Note

API またはパートナー センター ポータルを使用して、毎日の未請求の使用状況データを取得できます。 データが使用可能になるまでに最大 24 時間かかる場合があります。 ただし、場所やメーターが使用状況を報告するタイミングによっては、さらに遅延が発生する可能性があります。

場合によっては、前月の課金された使用状況データが配信されるまで、最新の未請求の使用状況データが表示されないことがあります。 これは、請求された使用状況データが合意された時間内に確実に配信されるようにするために行われます。 課金された使用状況データを受け取ると、月の初めから更新された未請求の使用状況データをすべて取得できるようになります。

重要

毎日評価される使用状況データには、次の製品の料金は含まれません。

• Azure 予約
• Azure 節約プラン
• Office
• Dynamics
• Microsoft Power Apps
• 永続的ソフトウェア
• ソフトウェア サブスクリプション
• サード パーティの SaaS 製品

API の概要

非同期 API は、管理可能なチャンク内の課金データと調整データにすばやくアクセスするための新しい方法です。 これにより、何時間も開いている接続をメインし、何百万ものトランザクションを繰り返しループする必要がなくなります。

バレット キー パターンと 非同期要求/応答 パターンを使用して、結果を非同期的に配信するように請求 API と調整 API を最適化しました。 API 応答は、すべての属性またはサブセットを使用して調整データにアクセスするためのトークンを提供します。

3 つの新しい手順 (API エンドポイント) を使用して、使用状況データを非同期的にダウンロードできます。 詳細については、以下を参照してください。

使用状況の行項目エンドポイント

課金対象または未請求の消費明細にアクセスするには、この API を使用します。 202 HTTP 状態と URL を含む場所ヘッダーが返されます。このヘッダーは、マニフェスト URL で成功状態を受け取るまで一定の間隔でポーリングする必要があります。

操作状態エンドポイント

成功状態になるまで、この API を定期的にポーリングし続けます。 要求されたデータが使用できない場合、API 応答には、別の要求を送信するまでの待機時間を示す Retry-After ヘッダーが含まれます。

マニフェスト エンドポイント

このエンドポイントは、実際の課金データをダウンロードできるストレージ フォルダーを提供します。 応答は、スループットと I/O 並列処理を最適化するためにファイルを分割またはパーティション分割します。

シーケンス図

次の図は、調整データをダウンロードするために必要な手順を示しています。

ユーザー アクション シーケンス

調整データを取得するには、次の手順に従います。

手順 1: 要求を送信する

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

未請求の使用明細項目を取得する

現在または最後のカレンダー月の未請求の使用明細項目を取得します。

API 要求

POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}

要求パラメーター

名前	In	必須	Type	説明
fragment	クエリ	False	String	完全な応答の場合は "full" を、属性のサブセットの場合は "basic" を選択します。 既定値は "full" です。この記事の 属性の一覧を 参照してください。
期間	クエリ	○	String	現在または最後のカレンダー月の使用状況を取得するには、"current" または "last" を使用します。 値 "last" は、既存の V1 API の "previous" と同じです。
currencyCode	クエリ	○	String	パートナーの請求通貨コード。

非推奨の要求パラメーター

新しい API バージョンでは、次の URI パラメーターは必要ありません。

名前	説明
プロバイダー	該当なし。 (すべての Azure プランの使用状況が返され、既存の V1 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 は他 の標準状態を返すことができます。

名前	説明
202 Accepted	要求は受け入れ済み。 要求の状態について、operation-location ヘッダー URL を照会します。

課金対象の使用明細項目を取得する

終了した請求期間の請求済みの使用明細項目を取得します。

API 要求

POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}

要求パラメーター

名前	In	必須	Type	説明
invoiceld	パス	True	String	パートナー センターの請求書番号。
Fragment	クエリ	False	String	完全な応答の場合は "full" を、属性のサブセットの場合は "basic" を選択します。 既定値は "full" です。この記事の 属性の一覧を 参照してください。

非推奨の要求パラメーター

新しい API バージョンでは、次の URI パラメーターは必要ありません。

名前	説明
プロバイダー	該当なし。 (すべての Azure プランの使用状況が返され、既存の V1 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 に基づいて、他の 標準状態を返すことができます。

名前	説明
202 Accepted	要求は受け入れ済み。 operation-location ヘッダー URL をポーリングして、要求の状態を確認します。

手順 2: 要求の状態を確認する

ターミナルの状態が成功または失敗した HTTP 200 を待ちます。 マニフェスト URL は、成功状態の "resourceLocation" になります。

操作状態を取得する

調整データ要求の状態を取得します。

API 要求

GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640

要求パラメーター

名前	In	必須	Type	説明
operationId	パス	True	String	操作 ID。

要求ヘッダー

この記事の API の要求ヘッダーの一覧を参照してください。

要求本文

該当なし。

応答の状態

この記事の標準の HTTP 状態 に加えて、API は HTTP 状態以下を返すことができます。

名前	説明
410 削除	各操作リンクは、指定されたサーバー制御時間に対してアクティブになります。 時間が経過した後、クライアントは新しい要求を送信する必要があります。

応答ペイロード

API 応答ペイロードは、次の属性を返します。

名前	省略可能	説明
createdDateTime	false	要求時刻。
lastActionDateTime	false	状態の変更時刻。
resourceLocation	true	マニフェスト ペイロード URI。
status	false	使用可能な値とアクション。

Value	クライアント側の処理
notstarted	"Retry-After" ヘッダーで指定された時刻を待機した後、状態をチェックする別の呼び出しを行います。
実行中	"Retry-After" ヘッダーで指定された時刻を待機した後、状態をチェックする別の呼び出しを行います。
succeeded	操作の最後の状態。データの準備ができていることを示します。 resourceLocation で指定された URI を使用してマニフェスト ペイロードを取得します。
失敗	永続的な障害を示すターミナル状態。 操作を再開します。

error 属性の場合:

名前	省略可能	説明
エラー	true	操作の状態が失敗した場合、json 形式で提供されるエラーの詳細。

名前	省略可能	説明
メッセージ	false	エラーについて詳しく説明します
code	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 は、"succeeded" 状態と "resourceLocation" URI を返します。

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: マニフェスト ペイロードを取得する

呼び出し元は、調整データが Azure BLOB に格納される場所の詳細を確認するために、マニフェスト URL に対して GET 要求を行います。

マニフェストの取得

調整データの Azure ストレージの場所に関する情報を持つマニフェストを取得します。

API 要求

GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}

要求パラメーター

名前	In	必須	Type	説明
manifestId	パス	True	String	マニフェスト ID。

要求ヘッダー

この記事の[API の要求ヘッダーの一覧]を参照してください。

要求本文

該当なし。

応答の状態

標準の HTTP 状態に加えて、API は HTTP 状態以下を返すことができます。

名前	説明
410 削除	各マニフェスト リンクは、指定されたサーバー制御時間に対してアクティブになります。 時間が経過した後、クライアントは新しい要求を送信する必要があります。

応答ペイロード

API 応答は、次の属性を返します。

名前	説明
バージョン	マニフェスト スキーマのバージョン。
dataFormat	課金データ ファイルの形式。 指定できる値 compressedJSONLines: 各 BLOB は圧縮ファイルであり、ファイル内のデータは JSON 行形式です。 ファイルを展開してデータにアクセスします。
utcCreatedDateTime	マニフェスト ファイルの作成時刻。
eTag,	マニフェスト データのバージョン。 課金情報を変更すると、新しい eTag 値が生成されます。
partnerTenantId	パートナー テナント ID。
rootFolder	ファイルのルート ディレクトリ。
rootFolderSAS	ファイルにアクセスするための SAS トークン。
partitionType	このプロパティは、データを分割します。 特定のパーティションにサポートされている数を超える数がある場合、データは "partitionValue" に対応する複数のファイルに分割されます。既定では、データはファイル内の行項目の数でパーティション分割されます。 コード内の固定数の行項目またはファイル サイズは変更される可能性があるため、設定しないでください。
blobCount	このパートナー テナント ID の合計ファイル数。
sizeInBytes	すべてのファイルの合計バイト数。
blobs	パートナー テナント ID のすべてのファイルの詳細を持つ "BLOB" オブジェクトの JSON 配列。
BLOB オブジェクト
名前	BLOB の名前。
sizeInBytes	BLOB サイズ (バイト単位)。
partitionValue	ファイルを含むパーティション。 大きなパーティションは、それぞれ同じ "partitionValue" を持つ複数のファイルに分割されます。

マニフェスト ペイロードのサンプル

{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"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 トークンを使用して、Azure BLOB ストレージから調整データをダウンロードします。 データを読み取る前に、Microsoft Azure Storage SDK/ツールを使用して BLOB をダウンロードし、BLOB ファイルを圧縮または解凍します。 データは JSON 行形式です。

標準 API 要求ヘッダー

すべての API は、次のヘッダーを受け入れます。

名前	必須	Type	説明
Authorization	True	String	承認ベアラー トークン。
ms-correlationid	False	String	内部要求トラッカー。 各要求では、新しいトラッカー (GUID) が生成されます。
ms-cv	False	String	内部要求トラッカー。
ms-requestid	False	String	要求のべき等 ID。

標準 API 応答の状態

API 応答からの HTTP 状態を次に示します。

名前	説明
400 要求が正しくありません	データが見つからないか、正しくありません。 エラーの詳細は、応答本文に含まれています。
401 権限がありません	呼び出し元は認証されないため、最初の呼び出しを行う前にパートナー API サービスで認証する必要があります。
403 無効	呼び出し元は要求を行う権限がありません。
500 内部サーバー エラー	API またはその依存関係の 1 つが要求を満たすことができません。 後で再度お試しください。
404 見つかりません	入力パラメーターではリソースを使用できません。
410 削除	マニフェスト リンクがタイムアウトまたは経過しました。 新しい要求を送信します。

使用状況データ属性

"full" または "basic" 要求パラメーターを指定した課金対象または未請求の使用状況 API 応答は、次の属性を返します。

属性	"full"	"basic"
PartnerId	はい	はい
PartnerName	はい	はい
CustomerId	はい	はい
顧客名	はい	はい
CustomerDomainName	はい	いいえ
CustomerCountry	はい	いいえ
MpnId	はい	いいえ
Tier2MpnId	はい	いいえ
InvoiceNumber	はい	はい
製品 ID	はい	はい
SkuId	はい	はい
AvailabilityId	はい	いいえ
SkuName	はい	はい
ProductName	はい	いいえ
パブリッシャー名 (PublisherName)	はい	はい
PublisherId	はい	いいえ
SubscriptionDescription	はい	いいえ
SubscriptionId	はい	はい
ChargeStartDate	はい	はい
ChargeEndDate	はい	はい
UsageDate	はい	はい
MeterType	はい	いいえ
測定カテゴリ （MeterCategory）	はい	いいえ
MeterId	はい	いいえ
測定サブカテゴリ （MeterSubCategory）	はい	いいえ
測定名 （MeterName）	はい	いいえ
測定範囲 （MeterRegion）	はい	いいえ
出荷単位	はい	はい
ResourceLocation	はい	いいえ
消費済みサービス （ConsumedService）	はい	いいえ
ResourceGroup	はい	いいえ
ResourceURI	はい	はい
ChargeType	はい	はい
UnitPrice	はい	はい
件数	はい	はい
UnitType	はい	いいえ
BillingPreTaxTotal	はい	はい
請求通貨 （BillingCurrency）	はい	はい
PricingPreTaxTotal	はい	はい
PricingCurrency	はい	はい
ServiceInfo1	はい	いいえ
ServiceInfo2	はい	いいえ
Tags	はい	いいえ
AdditionalInfo	はい	いいえ
EffectiveUnitPrice	はい	はい
PCToBCExchangeRate	はい	はい
EntitlementID	はい	はい
EntitlementDescription	はい	いいえ
PartnerEarnedCreditPercentage	はい	いいえ
CreditPercentage	はい	はい
CreditType	はい	はい
BenefitOrderID	はい	はい
BenefitID	はい	いいえ
BenefitType	はい	はい