請求済みの請求書調整 API v2 (GA)
適用対象: パートナー センター (ソブリン クラウドでは使用できません)
新しい非同期 API は、Azure BLOB を介して課金と調整のデータにすばやく効率的にアクセスする方法を提供します。 接続を何時間も開いたままにしたり、2,000 行の品目のバッチを処理したりする代わりに、ワークフローを合理化できるようになりました。
新しいコマース請求請求書調整 API では、valet キーやasynchronous request-reply パターンなどの高度な手法が使用されます。 この API には、すべての属性または課金される請求書調整データのサブセットにアクセスするために使用できる Shared Access Signature (SAS) トークンが用意されています。
MICROSOFT の API では、最適化された手法を使用して効率を向上させ、より少ない労力でより迅速な結果を得ることができます。 この API を利用して、データ アクセスを簡素化し、全体的な効率を向上させます。
Note
新しい API は、パートナー センター API ホストでホストされていません。 代わりに、MS Graph で見つけることができます Microsoft Graph API を使用してパートナーの課金データ (Microsoft Graph v1.0 をエクスポートします。 この API にアクセスするには、次の詳細を参照してください。
重要
アプリがパートナーの課金データにアクセスできるようにするには、このリンクに従って、Microsoft Graph の 認証と承認の基本について理解します。
Azure portal または Entra 管理センターを使用して、"PartnerBilling.Read.All" アクセス許可を割り当てることができます。 方法は以下のとおりです。
- [アプリの登録] セクションの Microsoft Entra ホーム ページでアプリを登録します。
- 必要なアクセス許可を付与するには、[API アクセス許可] セクションの Microsoft Entra App ページに移動します。 [アクセス許可の追加] を選択し、"PartnerBilling.Read.All" スコープを選択します。
これらの手順を完了することで、アプリがパートナーの課金データに必要なアクセス権を持っていることを確認できます。
API の概要
請求 新しいコマース 請求書調整明細を非同期的に取得できるように、2 つの主要な API エンドポイントが用意されています。 作業を開始するための合理化されたガイドを次に示します。
請求済みの請求書調整エンドポイント
最初に、この API を使用して、新しいコマース請求済みの請求書調整明細フェッチします。 要求を行うと、202 HTTP 状態と URL を含む場所ヘッダーが表示されます。 成功状態とマニフェスト URL が取得されるまで、この URL を定期的にポーリングします。
操作状態エンドポイント
次に、この 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 | いいえ | String | すべての属性に対して "full" を選択し、限定セットの場合は "basic" を選択します。 指定しない場合、既定値は "full" です。 このセクションの attributes の一覧を確認します。 省略可。 |
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 応答を受け取っていることを確認します。成功した場合は、"resourceLocation" 属性にマニフェスト URL が見つかります。 この属性は、必要な情報にアクセスするためのエンドポイントを提供します。
操作の状態を取得する
要求の状態を取得します。
API 要求
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
要求パラメーター
Name | に含める | 必須 | タイプ | 説明 |
---|---|---|---|---|
operationId | 要求 URI | True | String | 要求の状態を確認する一意の ID。 必須。 |
要求ヘッダー
Microsoft Graph を使用するためのベスト プラクティス 記載されている手順を使用して、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: エラーの種類。 |
リソースの場所オブジェクト
属性 | 内容 |
---|---|
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": "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 ストレージから請求済みの請求書調整明細項目をダウンロードする
まず、Shared Access Signature (SAS) トークンと BLOB ストレージの場所を取得する必要があります。 これらの詳細は、マニフェスト ペイロード API 応答の "sasToken" プロパティと "rootDirectory" プロパティで確認できます。 次に、BLOB ファイルをダウンロードして解凍するには、 Azure Storage SDK/toolを使用します。 JSONLines 形式です。
ヒント
サンプル コードを確認してください。 Azure BLOB ファイルをダウンロードしてローカル データベースに解凍する方法を示します。
標準 API 応答の状態
API 応答から次の HTTP 状態を取得できます。
コード | 説明 |
---|---|
400 – 不正な要求 | 要求が見つからないか、正しくないデータが含まれています。 エラーの詳細については、応答本文を確認してください。 |
401 – 未承認 | 最初の呼び出しを行う前に認証が必要です。 パートナー API サービスで認証します。 |
403 – 使用不可能 | 要求を行うために必要な承認がありません。 |
404お探しのページが見つかりませんでした | 指定された入力パラメーターでは、要求されたリソースを使用できません。 |
410 – ゴーン | マニフェスト リンクが無効またはアクティブになっています。 新しい要求を送信します。 |
500 - 内部サーバー エラー | API またはその依存関係は、現時点では要求を満たすことはできません。 後でもう一度試してみてください。 |
5000 – 使用可能なデータなし | システムには、指定された入力パラメーターのデータがありません。 |
請求済請求書調整明細属性
"full" または "basic" 属性セットについて、課金される請求書調整 API によって返される属性を比較するには、次の表を参照してください。 これらの属性の詳細については、「 recon ファイルの使用」を参照してください。
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 のサンプル。