収益のエクスポート要求を作成する

[アーティクル]
12/19/2023

この API を使用して、新しい収益と基になるトランザクション/支払いデータエクスポート要求をキューに入れ、収益とトランザクションのデータをスライスおよびサイコロにするオプションのフィルターを使用します。 202 HTTP 状態と要求 ID が返されます。これを使用して、キューに入ったトランザクションエクスポート要求の状態をチェックするためにポーリングできます。

トランザクション/収益の新しいエクスポート要求をキューに登録するために、API エンドポイントに POST 要求を送信します。

REST 要求

Method	要求 URI
投稿	`https://api.partner.microsoft.com/v1.0/payouts/transactionhistory?$filter={$filter}&fileformat=csv`

要求パラメーター

名前	/	必須	タイプ	説明
$filter	クエリ	いいえ	String	これは省略可能なフィルターですが、パフォーマンスを向上させるためにフィルターを使用し、過去 3 年間のデータをエクスポートするのではなく、エクスポートデータを制限することを強くお勧めします。 $filterオプションの完全なセットについては、次の表を参照してください。
fileFormat	クエリ	いいえ	String	サポートされている値は .csv/.tsv です。値が指定されていない場合、既定値は .csv です。

$filter クエリパラメーターは、エクスポート操作を作成するための省略可能なパラメーターです。ただし、エクスポートレポートのパフォーマンスを向上させ、可用性を向上させるには、$filtersを使用することを強くお勧めします。エクスポート操作の一部として使用できる主要な属性フィルターの一部を次に示します。

名前	Description	Type	サンプル
`enrollmentParticipantId`	組織の登録済み MPN ID。	int	{baseUrl}`/v1.0/payouts/transactionhistory?$filter= enrollmentParticipantId=12345`
`EarningForDate`	エクスポート操作の収益期間の日付。	DateTime	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=earningForDate ge 2023-03-01 and earningForDate le 2023-04-12`
`transactionAmount`	トランザクション量。	倍精度浮動小数点型	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=transactionAmount ge 2000 and transactionAmount le 5000`
`earningAmount`	トランザクション通貨での収益金額。	倍精度浮動小数点型	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=earningAmount ge 2000 and earningAmount le 5000`
`engagementName`	Microsoft Commerce インセンティブにのみ適用されます。値の例 - `'Azure CSP motion incentives - Indirect Provider'`.	String	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=engagementName=’Azure CSP motion incentives’`
`payableSubType`	収益の種類でフィルター処理します。値の例 - `'REBATE'`, `'COOP'`, , `'FEE''SELL'`	String	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payableSubType=’REBATE’ or payableSubType=’FEE’`
`payoutStatus`	支払いの状態でトランザクションをフィルター処理します。値の例 - `'SENT'`, `'UPCOMING'`, `'IN PROGRESS'`.	String	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payoutStatus=’IN PROGRESS’`

複数の要求パラメーターを含むサンプルトランザクション履歴フィルター:

”?$filter=earningForDate ge 2019-01-27T23:16:31.009Z and earningForDate le 2019-09-25T23:16:31.009Z and (enrollmentParticipantId eq 'XXXXXXX') and (programName eq ‘Microsoft Commerce Incentives’) and (payableSubType eq 'REBATE') and (paymentId eq '000000000000') and (engagementName eq 'Azure Enterprise and Self-Service Incentive' or engagementName eq 'Azure CSP motion incentives - Indirect Provider') and (leverCode eq ‘Azure Enterprise and Self-Service Motion’) and (payoutStatus eq 'SENT')”

要求ヘッダー

名前	Required	タイプ	説明
承認	はい	String	承認ベアラートークン。
ms-correlationid	いいえ	String	内部要求トラッカー。各要求では、新しいトラッカー (GUID) が生成されます。
ms-requestid	いいえ	String	要求のべき等 ID。

詳細については、パートナーセンターの REST ヘッダーを参照してください。

要求本文

該当なし。

API 応答

HTTP/1.1 202 Accepted

API 応答ペイロードは、次の属性を返します。

名前	省略可能	説明
Value	false	使用可能な値とアクションについては、次の表を参照してください。

使用可能な値とアクション

Value	クライアント側の処理
requestId	エクスポート要求の要求 ID
requestDateTime	エクスポート要求の開始日時
requestPath	エクスポート要求のクエリパス。
requestQueryString	エクスポート要求の一部として使用されるフィルター。
blobLocation	エクスポートファイルの準備ができたときにトークンを含む BLOB リソース
Status	エクスポート操作の状態。状態に使用できる値の一覧を次に示します。

状態に使用できる値

キューに入っている: エクスポート操作が開始されていません
処理: エクスポート操作が進行中です
失敗: 再試行後にエクスポート操作が失敗しました。新しい要求をキューに登録してみてください
完了: エクスポート操作が完了し、エクスポートファイルをダウンロードする準備ができました。

サンプル応答

{
    "value": [
        {
            "requestId": "93c2b3cf-c6d8-4e7e-ade1-007768a6eba4",
            "requestDateTime": "2023-05-25T21:20:46.3727561Z",
            "requestPath": "/v1.0/payouts/transactionhistory",
            "requestQueryString": "earningForDate ge 2023-03-01 and earningForDate le 2023-04-12",
            "blobLocation": "",
            "status": "Queued"
        }
    ],
    "nextLink": null,
    "totalCount": 1
}

API は HTTP 状態 202 を返します。

名前	説明
202 Accepted	要求が受け入れられました。要求の状態を GET 要求 URL に照会します。

要求に応じて、API は他の標準状態を返すことができます。

名前	説明
400 要求が正しくありません	データが見つからないか、正しくありません。
401 権限がありません	呼び出し元は認証されないため、最初の呼び出しを行う前にパートナー API サービスで認証する必要があります。
403 無効	呼び出し元は要求を行う権限がありません。
500 内部サーバーエラー	API またはその依存関係の 1 つが要求を満たすことができません。後でもう一度試してみてください。
404 見つかりません	入力パラメーターではリソースを使用できません。
429 レート制限	同じ型の要求が多すぎます。しばらくしてからお試しください。

Share via