创建收益导出请求

项目
12/19/2023

使用此 API 可将新的收益和基础交易/付款数据导出请求与可选筛选器排队，以切片和切分收益和交易数据。它返回 202 HTTP 状态和请求 ID，可用于轮询回检查排队事务导出请求的状态。

将 POST 请求提交到 API 终结点，以对事务/收益的新导出请求进行排队。

REST 请求

方法	请求 URI
POST	`https://api.partner.microsoft.com/v1.0/payouts/transactionhistory?$filter={$filter}&fileformat=csv`

请求参数

名称	在	必需	类型	描述
$filter	查询	否	字符串	尽管它是可选筛选器，但我们强烈建议使用筛选器来提高性能并限制导出数据，而不是导出过去三年的数据。有关完整的$filter选项集，请参阅下表。
fileFormat	查询	否	字符串	支持的值为 .csv/.tsv。如果未提供任何值，则默认为 .csv。

$filter查询参数是用于创建导出操作的可选参数。但是，我们强烈建议使用 $filters，以提高导出报表的性能和更快的可用性。以下是一些可用于导出操作的关键属性筛选器：

名称	说明	类型	示例
`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 商业奖励。示例值 - `'Azure CSP motion incentives - Indirect Provider'`.	字符串	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=engagementName=’Azure CSP motion incentives’`
`payableSubType`	按收入类型进行筛选。示例值 - `'REBATE'`、、 `'FEE''COOP''SELL'`	字符串	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payableSubType=’REBATE’ or payableSubType=’FEE’`
`payoutStatus`	按付款状态筛选交易。示例值 - `'SENT'`，， `'IN PROGRESS''UPCOMING'`。	字符串	{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')”

请求头文件

名称	必需	类型	说明
授权	是	字符串	授权持有者令牌。
ms-correlationid	否	字符串	内部请求跟踪器。每个请求都会生成一个新的跟踪器（GUID）。
ms-requestid	否	字符串	请求幂等 ID。

若要了解详细信息，请参阅合作伙伴中心 REST 标头

请求正文

不适用。

API 响应

HTTP/1.1 202 Accepted

API 响应有效负载返回以下属性：

名称	可选	说明
值	false	有关可能的值和操作，请参阅下表。

可能的值和操作

值	客户端操作
requestId	导出请求的请求 ID
requestDateTime	导出请求的启动日期/时间
requestPath	导出请求的查询路径。
requestQueryString	用作导出请求一部分的筛选器。
blobLocation	导出文件准备就绪时包含令牌的 Blob 资源
状态	导出操作状态。请参阅以下状态值列表。

状态的可能值

已排队：导出操作尚未启动
处理：正在执行导出操作
失败：重试后导出操作失败，请尝试对新请求进行排队
已完成：导出操作已完成，导出文件已准备好下载。

示例响应

{
    "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 已接受	已接受该请求。查询请求状态的 GET 请求 URL。

根据请求，API 可以返回其他标准状态：

名称	描述
400 错误请求	数据缺失或不正确。
401 未授权	调用方未进行身份验证，必须在进行第一次调用之前向合作伙伴 API 服务进行身份验证。
403 禁止访问	调用方无权发出请求。
500 内部服务器错误	API 或其依赖项之一无法满足请求。请稍后重试。
404 未找到	输入参数不可用的资源。
429 速率限制	相同类型的请求过多。请稍后再试。

通过