請求済みの請求書調整 API v2 (GA)

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

適用対象: パートナーセンター (ソブリンクラウドでは使用できません)

新しい非同期 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 をエクスポートします。この API にアクセスするには、次の詳細を参照してください。

重要

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

Azure portal または Entra 管理センターを使用して、"PartnerBilling.Read.All" アクセス許可を割り当てることができます。方法は以下のとおりです。

[アプリの登録] セクションの Microsoft Entra ホームページでアプリを登録します。
必要なアクセス許可を付与するには、Microsoft Entra アプリページに移動します。 [API のアクセス許可] セクションで、[アクセス許可の追加] を選択し、"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" です。このセクションの属性の一覧を確認します。省略可。
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	要求の状態を確認する一意の識別子。必須。

要求ヘッダー

要求本文

該当なし。

応答の状態

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

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

応答ペイロード

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

Attribute	必須	説明
id	True	各応答の一意の識別子必須。
status	True	値とアクション: Required。未開始の: "Retry-After" ヘッダーで指定した期間待機してから、別の呼び出しを行って状態を確認します。を実行している : "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"

            }

        \]

    }

}

手順 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 – 使用可能なデータなし	システムには、指定された入力パラメーターのデータがありません。

請求済請求書調整明細属性

課金済み請求書の調整 APIによって返される属性を、「full」または「basic」属性セットと比較するには、次の表を参照してください。これらの属性とその意味の詳細については、このガイドを参照してください。

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 v1 から v2 に移行するときに、これらの変更をメモしておきます。

各属性名は、ファイルとの一貫性を維持し、読みやすさを向上させるために、大文字の 文字で始まるようになりました。

サンプルコード

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

Partner-Center-Billing-Recon-Samples: パートナーセンター (github.com)から課金の再コンデータを取得するための API のサンプル。

次の方法で共有

請求済みの請求書調整 API v2 (GA)

API の概要

請求済みの請求書調整エンドポイント

操作状態エンドポイント

シーケンス図

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

手順 1: 要求を送信する

請求済みの請求書調整明細を取得する

API 要求

クエリパラメーター

要求本文

要求ヘッダー

API 応答

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

操作の状態を取得する

API 要求

要求パラメーター

要求ヘッダー

要求本文

応答の状態

応答ペイロード

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

API 要求

API 応答

API 要求

API 応答

手順 3: Azure BLOB ストレージから請求済みの請求書調整明細項目をダウンロードする

標準 API 応答の状態

請求済請求書調整明細属性

サンプルコード

フィードバック

その他のリソース

次の方法で共有

請求済みの請求書調整 API v2 (GA)

API の概要

請求済みの請求書調整エンドポイント

操作状態エンドポイント

シーケンス図

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

手順 1: 要求を送信する

請求済みの請求書調整明細を取得する

API 要求

クエリ パラメーター

要求本文

要求ヘッダー

API 応答

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

操作の状態を取得する

API 要求

要求パラメーター

要求ヘッダー

要求本文

応答の状態

応答ペイロード

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

API 要求

API 応答

API 要求

API 応答

手順 3: Azure BLOB ストレージから請求済みの請求書調整明細項目をダウンロードする

標準 API 応答の状態

請求済請求書調整明細属性

サンプル コード

フィードバック

その他のリソース

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

クエリパラメーター

サンプルコード