新しいコマースの毎日の評価使用量 v2 API (ベータ)
適用対象: パートナー センター | 21Vianet が運営するパートナー センター | Microsoft Cloud for US Government のパートナー センター
これらの API を使用して、 新しいコマース 課金および未請求の毎日の使用状況データを非同期的に取得します。
Note
この API は間もなく非推奨になります。 シームレスな操作を確実に行うために、GA バージョンに移行することをお勧めします。 事前に計画する必要がある詳細を次に示します。
目標: 2025 年 1 月 21 日より前の September 2022 から請求期間の日単位の評価済み使用明細項目を取得します。
アクション: この API を使用しますが、できるだけ早く v2 GA に移行します。
目標: 2025 年 1 月 21 日から September 2022 から請求期間の日単位で評価される使用量の明細項目を取得します。
アクション: API v2 GA のみを使用します。
目標: 2025 年 1 月 21 日より前の現在および以前の請求期間について、 非請求 日単位の使用明細項目を取得します。
アクション: この API を使用しますが、できるだけ早く v2 GA に移行します。
目標: 2025 年 1 月 21 日から現在および以前の請求期間について、 未請求 日単位の使用明細項目を取得します。
アクション: API v2 GA のみを使用します。
新しい API にシームレスに移行するには、次のリンクに従います: 毎日の課金および未請求の使用状況調整 API v2 (GA)。
ご注意いただき、ありがとうございます。また、課金 API で引き続き成功することを楽しみにしています。
Note
API またはパートナー センター ポータルを使用して、 非請求 日単位の使用明細項目にアクセスできます。 正確なデータを確保するには、最大 24 時間の可用性を確保します。 場所やメーターが使用状況を報告するタイミングによっては、さらに遅延が発生する可能性があります。
最初に、請求日単位の使用状況データの時間配信に優先順位を付けます。 場合によっては、前月の課金される使用状況データが使用可能になるまで、最新の日単位の評価された使用状況データが表示されないことがあります。 課金された使用状況データを受け取ったら、月の初めから更新された未請求の使用状況データをすべて取得できます。
私たちは可能な限り正確でタイムリーな情報を提供するよう努めるので、あなたの理解と忍耐を感謝しています。
重要
毎日評価される使用状況データには、次の製品の料金は含まれません。
- Azure 予約
- Azure 節約プラン
- Office
- Dynamics
- Microsoft Power Apps
- 永続的ソフトウェア
- ソフトウェア サブスクリプション
- Microsoft 以外またはマーケットプレースの SaaS 製品
API の概要
非同期 API は、管理可能なチャンク内の課金データと調整データにすばやくアクセスするための新しい方法です。 これにより、何時間も開いている接続を維持し、何百万ものトランザクションを繰り返しループする必要がなくなります。
検証キーと asynchronous request-reply パターンを使用して、結果を非同期的に配信するように請求 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 | 説明 |
---|---|---|---|---|
フラグメント | クエリ | 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 応答ペイロードは、次の属性を返します。
Name | 省略可能 | 説明 |
---|---|---|
createdDateTime | false | 要求時刻。 |
lastActionDateTime | false | 状態の変更時刻。 |
resourceLocation | true | マニフェスト ペイロード URI。 |
status | false | 使用可能な値とアクション。 |
Value | クライアント側の処理 |
---|---|
notstarted | "Retry-After" ヘッダーで指定された時刻を待機した後に状態を確認する別の呼び出しを行います。 |
実行中 | "Retry-After" ヘッダーで指定された時刻を待機した後に状態を確認する別の呼び出しを行います。 |
succeeded | 操作の最後の状態。データの準備ができていることを示します。 resourceLocation で指定された URI を使用してマニフェスト ペイロードを取得します。 |
失敗 | 永続的な障害を示すターミナル状態。 操作を再開します。 |
error 属性の場合:
Name | 省略可能 | 説明 |
---|---|---|
エラー | true | 操作の状態が失敗した場合、json 形式で提供されるエラーの詳細。 |
Name | 省略可能 | 説明 |
---|---|---|
メッセージ | 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 の要求ヘッダーの一覧]を参照してください。
要求本文
該当なし。
応答の状態
名前 | 説明 |
---|---|
410 削除 | 各マニフェスト リンクは、指定されたサーバー制御時間に対してアクティブになります。 時間が経過した後、クライアントは新しい要求を送信する必要があります。 |
応答ペイロード
API 応答は、次の属性を返します。
名前 | 説明 |
---|---|
バージョン | マニフェスト スキーマのバージョン。 |
dataFormat | 課金データ ファイルの形式。 指定できる値 compressedJSONLines: 各 BLOB は圧縮ファイルであり、ファイル内のデータは JSON 行 形式です。 データにアクセスするには、ファイルを展開します。 |
utcCreatedDateTime | マニフェスト ファイルの作成時刻。 |
eTag | マニフェスト データのバージョン。 課金情報を変更すると、新しい eTag 値が生成されます。 |
partnerTenantId | パートナー テナント ID。 |
rootFolder | ファイルのルート ディレクトリ。 |
rootFolderSAS | ファイルにアクセスするための SAS トークン。 |
partitionType | このプロパティは、データを分割します。 特定のパーティションにサポートされている数を超える数がある場合、データは "partitionValue" に対応する複数のファイルに分割されます。既定では、ファイル内の行項目の数に基づいてデータがパーティション分割されます。 パーティション分割の原則が変更される可能性があるため、コードで固定数の行項目またはファイル サイズを設定しないでください。 |
blobCount | このパートナー テナント ID の合計ファイル数。 |
sizeInBytes | すべてのファイルの合計バイト数。 |
blobs | パートナー テナント ID のすべてのファイルの詳細を持つ "BLOB" オブジェクトの JSON 配列。 |
BLOB オブジェクト | |
Name | BLOB の名前。 |
sizeInBytes | BLOB サイズ (バイト単位)。 |
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: ストレージの場所から使用状況調整データをダウンロードする
マニフェスト ペイロード API 応答の "rootFolderSAS" プロパティと "rootFolder" プロパティから SAS トークンと BLOB ストレージの場所を取得します。 Azure Storage SDK/ツールを使用して、BLOB ファイルをダウンロードして解凍します。 JSON行形式です。
標準 API 要求ヘッダー
すべての API は、次のヘッダーを受け入れます。
名前 | 必須 | Type | 説明 |
---|---|---|---|
Authorization | True | String | 承認ベアラー トークン。 |
ms-correlationid | いいえ | String | 内部要求トラッカー。 各要求では、新しいトラッカー (GUID) が生成されます。 |
ms-cv | いいえ | String | 内部要求トラッカー。 |
ms-requestid | いいえ | String | 要求のべき等 ID。 |
標準 API 応答の状態
API 応答からの HTTP 状態を次に示します。
名前 | 説明 |
---|---|
400 Bad Request | データが見つからないか、正しくありません。 エラーの詳細は、応答本文に含まれています。 |
401 権限がありません | 呼び出し元は認証されないため、最初の呼び出しを行う前にパートナー API サービスで認証する必要があります。 |
403 無効 | 呼び出し元は要求を行う権限がありません。 |
500 内部サーバー エラー | API またはその依存関係の 1 つが要求を満たすことができません。 後でもう一度試してみてください。 |
404 見つかりません | 入力パラメーターではリソースを使用できません。 |
410 削除 | マニフェスト リンクがタイムアウトまたは経過しました。 新しい要求を送信します。 |
使用状況データ属性
"full" または "basic" 要求パラメーターを指定した課金対象または未請求の使用状況 API 応答は、次の属性を返します。
属性 | "full" | "basic" |
---|---|---|
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 | はい | はい |