請求済みの請求書調整 API v2 (GA)
適用対象: パートナー センター (ソブリン クラウドでは使用できません)
非同期 API を使用すると、Azure BLOB を介して課金と調整のデータにアクセスする、より迅速かつ管理しやすい方法が提供されます。 この API を使用すると、接続を何時間も開いたままにしておく必要も、一度に 2,000 行の項目のバッチをループする必要はありません。
バレット キーと非同期の要求/応答パターンを使用して、新しいコマース課金請求書調整 API を最適化しました。 この API には、すべての属性または課金される請求書調整データのサブセットにアクセスするために使用できる Shared Access Signature (SAS) トークンが用意されています。
Note
新しい API は、パートナー センター API ホストでホストされていません。 代わりに、MS Graph で Microsoft Graph API を使用してパートナーの課金データ (Microsoft Graph v1.0) をエクスポートできます。 この API にアクセスするには、次の詳細を参照してください。
この API は、MS Graph のパブリック/グローバル クラウドに対してのみ使用できます。 Azure Government、Azure Germany、または Azure China 21Vianet では、まだ使用できません。
API の概要
請求された 新しいコマース 請求書調整データを非同期的に取得するには、2 つの API エンドポイントを使用します。 そのプロセスを次に示します。
請求済みの請求書調整エンドポイント
この API を使用して、新しいコマース請求請求書調整明細を取得します。 API は、202 HTTP 状態と URL を含む場所ヘッダーを返します。 マニフェスト URL で成功状態が得られるまで、この URL を定期的にポーリングします。
操作状態エンドポイント
成功状態を取得するには、この API を一定の間隔で呼び出し続けます。 データの準備ができていない場合、API 応答には Retry-After ヘッダーが含まれており、再試行するまでの待機時間を示します。 操作が完了すると、使用状況データをダウンロードできるストレージ フォルダーを含むマニフェスト リソースが取得されます。 応答により、スループットと I/O 並列処理を最適化するために、ファイルがより小さな部分に分割されます。
シーケンス図
新しいコマース請求書調整データをダウンロードする手順を示すシーケンス図を次に示します。
ユーザー アクション シーケンス
請求された請求書調整データを取得するには、次の手順に従います。
手順 1: 要求を送信する
API エンドポイントに POST 要求を送信します。
請求済みの請求書調整明細を取得する
API 要求
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
クエリ パラメーター
該当なし
要求本文
| Attribute | 必須 | タイプ | 説明 |
|---|---|---|---|
| attributeSet | False | String | すべての属性に対して "full" を選択し、限定セットの場合は "basic" を選択します。 既定値は "full" です。(この記事の属性の 一覧を 参照してください)。 省略可能。 |
| invoiceld | True | String | 各請求書の一意の識別子。 必須。 |
要求ヘッダー
Microsoft Graph を使用するためのベスト プラクティスに記載されている手順を使用して、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 を照会します。 |
手順 2: 要求の状態を確認する
要求の状態をチェックするには、"成功" または "失敗" のいずれかの状態の HTTP 200 応答を待ちます。要求が成功した場合、マニフェスト URL は "resourceLocation" 属性で取得されます。
操作の状態を取得する
要求の状態を取得します。
API 要求
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
要求パラメーター
| 名前 | に含める | 必須 | タイプ | 説明 |
|---|---|---|---|---|
| operationId | 要求 URI | True | String | 要求の状態をチェックする一意の ID。 必須。 |
要求ヘッダー
Microsoft Graph を使用するためのベスト プラクティスに記載されている手順を使用して、API のヘッダーを要求します。
要求本文
該当なし。
応答の状態
この記事の Standard API 応答の状態に 記載されている標準の HTTP 状態 に加えて、API は次の HTTP 状態を返すことができます。
| コード | 説明 |
|---|---|
| 410 – ゴーン | マニフェスト リンクは、設定された時間が経過すると期限切れになります。 マニフェスト リンクをもう一度取得するには、新しい要求を送信します。 |
応答ペイロード
API 応答ペイロードには、次の属性が含まれています。
| Attribute | 必須 | 内容 |
|---|---|---|
| id | True | 各応答の一意の ID 必須。 |
| status | True | 値とアクション: 必須。 notstarted: "Retry-After" ヘッダーで指定された時刻を待ってから、状態をチェックする別の呼び出しを行います。 running: "Retry-After" ヘッダーで指定された時刻を待ってから、状態をチェックする別の呼び出しを行います。 成功: データの準備ができました。 resourceLocation で指定された URI を使用してマニフェスト ペイロードを取得します。 failed: 操作は永続的に失敗しました。 再起動します。 |
| createdDateTime | True | 要求が行われた時刻。 必須。 |
| lastActionDateTime | True | 状態が最後に変更された時刻。 必須。 |
| resourceLocation | False | マニフェスト ペイロードの URI。 省略可能。 |
| エラー | False | 操作が失敗した場合、エラーの詳細は JSON 形式で提供されます。 省略可能。 次の属性が含まれています。 message: エラーの詳細な説明。 code: 発生したエラーの種類。 |
リソースの場所オブジェクト
| 属性 | 内容 |
|---|---|
| id | マニフェストの一意識別子。 |
| schemaVersion | マニフェスト スキーマのバージョン。 |
| dataFormat | 課金データ ファイルの形式。 compressedJSON: 各 BLOB が JSON 行形式のデータを含む圧縮ファイルであるデータ形式。 各 BLOB からデータを取得するには、データを展開します。 |
| createdDateTime | マニフェスト ファイルが作成された日時。 |
| eTag | マニフェスト データのバージョン。 課金情報を変更すると、新しい値が生成されます。 |
| partnerTenantId | パートナーのテナントの ID。 |
| rootDirectory | ファイルのルート ディレクトリ。 |
| sasToken | ディレクトリのすべてのファイルを読み取る SAS (Shared Access Signature) トークン。 |
| partitionType | partitionValue 属性に基づいてデータを複数の BLOB に分割します。 システムは、サポートされている数を超えるパーティションを分割します。 既定では、データはファイル内の行項目の数に基づいてパーティション分割されます。 これらの値は変更される可能性があるので、コードで固定数の行項目またはファイル サイズを設定しないでください。 |
| blobCount | このパートナー テナント ID のファイルの合計数。 |
| blobs | パートナー テナント ID のファイルの詳細を含む "BLOB" オブジェクトの JSON 配列。 |
| BLOB オブジェクト | 次の詳細を含むオブジェクト。 name: BLOB の名前。 partitionValue: ファイルを含むパーティション。 大きなパーティションは複数のファイルに分割され、各ファイルには同じ "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": "0e195b37-4574-4539-bc42-0e539b9684c0",
"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: Azure BLOB ストレージから課金された請求書調整データをダウンロードする
マニフェスト ペイロード API 応答の "sasToken" プロパティと "rootDirectory" プロパティから、Shared Access Signature (SAS) トークンと BLOB ストレージの場所を取得します。 BLOB ファイルをダウンロードして解凍するための Azure Storage SDK/ツール 。 JSONLines 形式です。
ヒント
標準 API 応答の状態
API の応答から次の HTTP 状態を取得できます。
| コード | 説明 |
|---|---|
| 400 – 不正な要求 | 要求が見つからないか、正しくないデータが含まれています。 エラーの詳細については、応答本文を確認してください。 |
| 401 – 未承認 | 呼び出し元は認証されていないため、最初の呼び出しを行う前にパートナー API サービスで認証する必要があります。 |
| 403 – 使用不可能 | 要求を行うために必要な承認がありません。 |
| 404お探しのページが見つかりませんでした | 指定された入力パラメーターでは、要求されたリソースを使用できません。 |
| 410 – ゴーン | マニフェスト リンクが有効またはアクティブではなくなりました。 新しい要求を送信します。 |
| 500 - 内部サーバー エラー | API またはその依存関係の 1 つは、現時点では要求を満たすことはできません。 後でもう一度試してみてください。 |
請求済みの請求書調整データ属性
"full" または "basic" 属性セットについて、課金される請求書調整 API によって返される属性を比較するには、次の表を参照してください。
| Attribute | 完全 | 基本 |
|---|---|---|
| PartnerId | はい | はい |
| CustomerId | はい | はい |
| CustomerName | はい | はい |
| CustomerDomainName | はい | いいえ |
| CustomerCountry | はい | いいえ |
| InvoiceNumber | はい | はい |
| MpnId | はい | いいえ |
| Tier2MpnId | はい | はい |
| OrderId | はい | はい |
| OrderDate | はい | はい |
| 製品 ID | はい | はい |
| SkuId | はい | はい |
| AvailabilityId | はい | はい |
| SkuName | はい | いいえ |
| ProductName | はい | はい |
| 料金の種類 （ChargeType） | はい | はい |
| UnitPrice | はい | はい |
| 数量 （Quantity） | はい | いいえ |
| 小計 | はい | はい |
| TaxTotal | はい | はい |
| トータル | はい | はい |
| 通貨 | はい | はい |
| PriceAdjustmentDescription | はい | はい |
| 発行元 | はい | はい |
| PublisherId | はい | いいえ |
| SubscriptionDescription | はい | いいえ |
| SubscriptionId | はい | はい |
| ChargeStartDate | はい | はい |
| ChargeEndDate | はい | はい |
| TermAndBillingCycle | はい | はい |
| EffectiveUnitPrice | はい | はい |
| UnitType | はい | いいえ |
| AlternateId | はい | いいえ |
| 請求対象となる数量 | はい | はい |
| BillingFrequency | はい | いいえ |
| PricingCurrency | はい | はい |
| PCToBCExchangeRate | はい | はい |
| PCToBCExchangeRateDate | はい | いいえ |
| MeterDescription | はい | いいえ |
| ReservationOrderId | はい | はい |
| CreditReasonCode | はい | はい |
| SubscriptionStartDate | はい | はい |
| SubscriptionEndDate | はい | はい |
| ReferenceId | はい | はい |
| ProductQualifiers | はい | いいえ |
| PromotionId | はい | はい |
| ProductCategory | はい | はい |
サンプル コード
API の使用に関するガイダンスについては、C# のサンプル コードを含む次のリンクを参照してください。
Partner-Center-Billing-Recon-Samples: パートナー センター (github.com) から課金の再コンデータを取得するための API のサンプル。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示