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

適用対象: パートナー センター (Azure Government または Azure China 21Vianet では利用できません)

アーキテクチャを理解する

新しい非同期 API では、課金と調整のデータ アクセスを処理する方法が大幅に進化しています。 このアプローチは、有効期間の長い接続の維持や大規模なデータ バッチの処理など、従来の同期方法に関連する課題を解決します。 この API の主な利点とメカニズムを次に示します。

主なコンポーネント

バレット キー パターンによる安全なアクセス

バレット キー パターンは、課金データへの安全で制限されたアクセスを提供します。 バレットキーを使用すると、トランクにアクセスせずに車を運転できるのと同様に、このパターンによってきめ細かなアクセス制御が可能になります。 共有アクセス署名 (SAS) トークンは、資格情報を共有する代わりに、特定のリソースへの制限付き期限付きアクセスを許可します。 このパターンでは、正確な有効期限とアクセス許可を構成することで、不正アクセスのリスクを軽減します。

非同期の要求/応答パターンによる効率の向上

忙しいレストランでの注文と考えてください。 カウンターで待つ代わりにブザーを受け取り、注文の準備中に他のことを行うことができます。 データの準備ができたら、システムから通知が表示されます。

API の非同期的な性質は、要求を行い、システムがバックグラウンドで処理することを意味します。 この 非同期要求応答 では、リソースを効率的に使用し、サーバーの負荷を軽減し、同期データ取得と共通のタイムアウトとエラーを最小限に抑えます。

データ アクセス許可の柔軟性

SAS トークンを使用すると、データ アクセス許可を柔軟に管理できます。 課金される請求書調整データのすべての属性へのアクセスを許可するトークンを生成したり、特定のサブセットへのアクセスを制限したりすることができます。 この細分性により、組織は内部ポリシーと規制要件に従ってデータ アクセスを調整し、セキュリティとコンプライアンスを強化できます。

ワークフローの簡素化とデータ処理時間の向上

非同期の要求/応答パターンは、2,000 行の固定バッチではなく動的アクセスを許可することで、データ処理を効率化します。 このアプローチにより、結果が速くなり、処理時間が短縮され、既存のシステムとワークフローへの課金と調整データの統合が簡略化されます。

メリット

1. パフォーマンスの利点

   新しいシステムでは、有効期間の長い接続を維持し、固定バッチを処理する代わりに、次のことができます。

   • 迅速な初期要求を行います。
   • セキュリティで保護されたアクセス トークンを受け取ります。
   • 自分のペースでデータを処理します。
   • 必要なときに必要な情報に正確にアクセスできます。

2. セキュリティの強化

   SAS トークンを使用して実装されるバレット キー パターンでは、次の機能が提供されます。

   • 時間制限付きアクセス。
   • 制限付きアクセス許可。
   • 永続的な資格情報の共有または保存の排除。
   • きめ細かいアクセス制御。

3. アーキテクチャの利点

   非同期の要求/応答パターンは、次のようなパーソナル アシスタントのように機能します。

   • 要求を受け取ります。
   • バックグラウンドでタスクを処理します。
   • 準備ができたら通知します。

最適化された API を採用してパフォーマンスを向上させる

これらの最適化された API を採用すると、ワークフローが合理化され、データ管理の全体的なパフォーマンスが向上します。 安全なアクセス制御と効率的な取得メカニズムを使用すると、より少ない労力でより優れた結果が得られ、運用効率が向上します。

結論として、Azure BLOB を介して課金データと調整データにアクセスするための新しい非同期 API は強力なツールです。 セキュリティとコンプライアンスが高く、財務データへの安全で効率的なアクセス、ワークフローの合理化、サーバーの負荷の削減、処理時間の向上を実現します。

現時点では、これらの API は MS Graph パブリック グローバル クラウドにのみ使用できます。 Azure Government または Azure China ではまだ使用できません。

アプリがパートナーの課金データにアクセスできるようにする

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

PartnerBilling.Read.All アクセス許可を割り当てる

Azure portal または Microsoft Entra 管理センターを使用して、"PartnerBilling.Read.All" アクセス許可を割り当てます。 これらの手順により、アプリがパートナーの課金データに必要なアクセス権を持っていることを確認します。

1. [アプリの登録] セクションの Microsoft Entra ホーム ページでアプリを登録します。
2. Microsoft Entra App ページに移動して、必要なアクセス許可を付与します。 [API のアクセス許可] セクションで、[アクセス許可 の追加] を選択し、PartnerBilling.Read.All スコープを選択します。

ベータ版と GA バージョンの違いを理解する

ベータ版を使用している場合は、一般提供 (GA) バージョンへの移行がスムーズで直感的である可能性があります。 更新プログラムと機能強化を理解するために、ベータ版と GA バージョン 比較することをお勧めします。 これらの更新プログラムを理解すると、GA バージョンで使用できる新機能と機能強化を最大限に活用できます。

API エンドポイントを理解して使用する

課金対象の 新しいコマース 毎日評価される使用状況の行項目を非同期的に取得できるように、2 つの主要な API エンドポイントが用意されています。 この合理化されたガイドに従って、すぐに開始してください。

行項目エンドポイントを使用する

最初に、この API を使用して、毎日評価 利用明細項目 新しいコマースを取得します。 要求を行うと、202 HTTP 状態と URL を含む場所ヘッダーが表示されます。 成功状態とマニフェスト URL が取得されるまで、この URL を定期的にポーリングします。

操作状態エンドポイントを使用する

これらの手順に従うことで、請求書調整プロセスを効率的に管理できます。

この API を定期的に呼び出して、操作の状態を確認し続けます。 データの準備ができていない場合、応答には、再試行するまでの待機時間を示す Retry-After ヘッダーが含まれます。 操作が完了すると、使用状況データをダウンロードするためのストレージ フォルダー リンクを含むマニフェスト リソースが表示されます。 応答によってファイルがセグメント化され、スループットが向上し、I/O 並列処理が可能になります。

調整データ シーケンス図を確認する

調整データをダウンロードする手順を示すシーケンス図を次に示します。

ユーザー アクション シーケンスに従う

新しいコマース の毎日評価された使用量の調整明細項目 を取得するためのユーザーが行うべき手順を次に示します。

• リクエストを送信する
• 要求の状態を確認
• Azure BLOB ストレージから調整項目をダウンロードする

要求を送信する

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

1 日ごとの課金対象の使用状況の明細項目を取得する

現在 または最後のカレンダー月または請求期間 新しいコマース未請求の日単位の使用状況の明細項目を取得します。

API 要求

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

要求本文

要求ヘッダー

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 応答の状態 」セクションに記載されています。

請求日単位の使用状況の明細項目を取得する

新しいコマースを取得支払い済みの請求期間の請求書に対して毎日評価される使用状況の明細項目が課金されます。

API 要求

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

クエリ パラメーター

該当なし

要求本文

要求ヘッダー

API の要求ヘッダー。 詳細については、 責任とサポートを参照してください。

API 応答

HTTP/1.1 202 Accepted
場所: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

API を使用すると、通常は HTTP 202 状態が返されます。 要求に応じて返される可能性のあるその他の状態については、状態を参照してください。

要求の状態を確認する

要求の状態を追跡するには、"成功" または "失敗" を示す標準の状態コードである HTTP 200 応答を受け取っていることを確認します。成功した場合は、"resourceLocation" 属性にマニフェスト URL が指定されています。 この属性は、必要な情報にアクセスするためのエンドポイントを提供します。

操作の状態を取得する

要求の状態を取得します。

API 要求

取得 https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

要求パラメーター

要求ヘッダー

API のヘッダーを要求するには、「 責任とサポートを参照してください。

要求本文

該当なし。

応答の状態

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

応答ペイロード

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

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

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"

            }

        \]

    }

}

Azure BLOB ストレージから調整項目をダウンロードする

まず、Shared Access Signature (SAS) トークンと BLOB ストレージの場所 (ルート ディレクトリと BLOB 名を組み合わせる) を取得する必要があります。 これらの詳細については、マニフェスト ペイロード API 応答の sasToken、 rootDirectory、および blobs プロパティを参照してください。

続行するには、次の手順に従います。

1. Azure Storage SDK/ツールを使用して BLOB ファイルをダウンロードします。
2. JSONLines 形式のファイルを解凍します。

標準の API 応答の状態を理解する

API 応答から次の HTTP 状態を受け取る場合があります。

ベータ版と GA バージョンを比較する

ベータ版と一般公開 (GA) バージョンの違いについては、次の比較表を参照してください。 現在ベータ版を使用している場合、GA バージョンへの移行は簡単で簡単です。

基本と完全な日単位の使用状況調整属性を比較する

"full" または "basic" の属性セットについて、請求済みまたは未請求の使用状況調整 API によって返される属性を比較するには、次の表を参照してください。 これらの属性とその意味の詳細については、毎日評価される使用状況調整 ファイルの フィールドを参照してください。

サンプル コード

この API への移行に関するサポートが必要な場合は、C# サンプル コードを含むリンクを参照してください。

パートナー センター API のサンプル: 課金の調整データを取得する。

関連コンテンツ

• パートナーの請求データをエクスポートするための Microsoft Graph API
• Azure Storage SDK/ツール