商业市场的编程访问范例
下图演示了用于创建新的报表模板、计划自定义报表和检索失败数据的 API 调用模式。
图 1：API 调用模式的高级流
此列表提供了有关图 1 的更多详细信息。
- 客户端应用程序可以通过调用“创建报表查询”API 来定义自定义的报表架构/模板。 或者，你可以使用系统查询列表中的报表模板 (
QueryId)。 - 成功后，“创建报表模板”API 将返回
QueryId。 - 然后，客户端应用程序使用
QueryID并结合报表开始日期、重复间隔、重复周期和可选的回调 URI 来调用“创建报表”API。 - 成功后，“创建报表”API 将返回
ReportID。 - 只要报表数据可供下载，就会立即通过回调 URI 向客户端应用程序发出通知。
- 然后，客户端应用程序使用“获取报表执行”API 并结合
Report ID和日期范围来查询报表的状态。 - 成功时，会返回报告下载链接，并且应用程序可以启动数据下载。
报表查询语言规范
尽管我们提供了可用于创建报表的系统查询，但你也可以根据业务需求创建自己的查询。 若要详细了解自定义查询，请参阅自定义查询规范。
“创建报表查询”API
此 API 可帮助创建自定义查询，用于定义需要从中导出列和指标的数据集。 该 API 可让你灵活地根据业务需求创建新的报告模板。
你也可以使用我们提供的系统查询。 不需要自定义报表模板时，可以使用我们提供的系统查询的 QueryId 直接调用“创建报表 API”。
以下示例演示如何创建自定义查询，以从上个月的 ISVUsage 数据集中获取付费 SKU 的规范化使用量和预估财务费用。
请求语法
| 方法 | 请求 URI |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries |
请求标头
| 标头 | 类型 | 说明 |
|---|---|---|
| 授权 | 字符串 | 必需。 Microsoft Entra 访问令牌。 格式为 Bearer <token>。 |
| Content-Type | string |
application/JSON |
路径参数
无
查询参数
无
请求有效负载示例
{
"Name": "ISVUsageQuery",
"Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}
术语表
此表提供了请求有效负载中元素的关键定义。
| 参数 | 必需 | 说明 | 允许的值 |
|---|---|---|---|
Name |
是 | 查询的用户友好名称 | string |
Description |
否 | 所创建的查询的说明 | string |
Query |
是 | 基于业务需求的查询字符串 | string |
注意
有关自定义查询示例，请参阅 示例查询。
示例响应
响应有效负载的结构如下：
响应代码：200、400、401、403、500
响应有效负载示例：
{
"value": [
{
"queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
"name": " ISVUsageQuery",
"description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
"type": "userDefined",
"user": "142344300",
"createdTime": "2024-01-06T05:38:34Z"
}
],
"totalCount": 1,
"message": "Query created successfully",
"statusCode": 200
}
术语表
此表提供了响应中元素的关键定义。
| 参数 | 说明 |
|---|---|
QueryId |
创建的查询的通用唯一标识符 （UUID） |
Name |
在创建查询期间请求有效负载中提供的名称 |
Description |
在创建查询期间请求有效负载中提供的说明 |
Query |
在创建查询期间在请求有效负载中提供的自定义报表查询 |
Type |
userDefined设置为手动创建的查询 |
User |
用于创建查询的用户 ID |
CreatedTime |
创建查询时的 UTC 时间。 格式：yyyy-MM-ddTHH：mm：ssZ |
TotalCount |
Value 数组中的记录数 |
StatusCode |
结果代码 可能的值为 200、400、401、403、500 |
message |
执行 API 后显示的状态消息 |
“创建报表”API
如果成功创建自定义报表模板后收到了作为创建报表查询响应的一部分的 QueryID，可以调用此 API 来计划一个定期执行的查询。 可以针对要传送的报表设置频率和计划。 对于我们提供的系统查询，还可以使用 QueryId 调用“创建报表”API。
请求语法
| 方法 | 请求 URI |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport |
请求标头
| 标头 | 类型 | 说明 |
|---|---|---|
| 授权 | 字符串 | 必需。 Microsoft Entra 访问令牌。 格式为 Bearer <token>。 |
| 内容类型 | string | application/JSON |
路径参数
无
查询参数
无
请求有效负载示例
{
"ReportName": "ISVUsageReport",
"Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
"StartTime": "2021-01-06T19:00:00Z ",
"executeNow": false,
"RecurrenceInterval": 48,
"RecurrenceCount": 20,
"Format": "csv",
"CallbackUrl": "https://<SampleCallbackUrl>"
"callbackMethod": "GET",
}
术语表
此表提供了请求有效负载中元素的关键定义。
| 参数 | 必需 | 说明 | 允许的值 |
|---|---|---|---|
ReportName |
是 | 分配给报表的用户友好名称 | 字符串 |
Description |
否 | 创建的报表的说明 | 字符串 |
QueryId |
是 | 需要用于生成报表的查询 ID | 字符串 |
StartTime |
是 | 开始生成报表时的 UTC 时间戳。 格式应为 yyyy-MM-ddTHH:mm:ssZ | 字符串 |
ExecuteNow |
否 | 此参数应用于创建只执行一次的报表。 StartTime如果设置为 ，则忽略 EndTime>。 RecurrenceCounttrue |
布尔 |
QueryStartTime |
否 | （可选）指定用于提取数据的查询的开始时间。 此参数仅适用于 ExecuteNow 设置为 true 的一次性执行报表。 格式应为 yyyy-MM-ddTHH:mm:ssZ |
字符串形式的时间戳 |
QueryEndTime |
否 | （可选）指定用于提取数据的查询的结束时间。 此参数仅适用于 ExecuteNow 设置为 true 的一次性执行报表。 格式应为 yyyy-MM-ddTHH:mm:ssZ |
字符串形式的时间戳 |
RecurrenceInterval |
是 | 报表生成频率，以小时为单位。 最小值为 1，最大值为 17520 | Integer |
RecurrenceCount |
是 | 要生成的报表数。 限制取决于定期间隔 | Integer |
Format |
否 | 导出的文件的文件格式。 默认格式为 CSV | CSV/TSV |
CallbackUrl |
否 | 可选择性地配置为回调目标的可公开访问 URL | 字符串 |
CallbackMethod |
否 | 可以使用回调 URL 配置的 Get/Post 方法 | GET/POST |
EndTime |
是 | 报表生成将结束的 UTC 时间戳。 格式应为 yyyy-MM-ddTHH:mm:ssZ | 字符串 |
注意
创建报表时，必须EndTime进行或组合RecurrenceIntervalRecurrenceCount。
示例响应
响应有效负载的结构如下：
响应代码：200、400、401、403、404、500
响应有效负载：
{
"Value": [
{
"reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
"reportName": "ISVUsageReport",
"description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
"query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
"user": "142344300",
"createdTime": "2024-01-06T05:46:00Z",
"modifiedTime": null,
"startTime": "2024-01-06T19:00:00Z",
"reportStatus": "Active",
"recurrenceInterval": 48,
"recurrenceCount": 20,
"callbackUrl": "https://<SampleCallbackUrl>",
"callbackMethod": "GET",
"format": "csv"
}
],
"TotalCount": 1,
"Message": "Report created successfully",
"StatusCode": 200
}
术语表
此表提供了响应中元素的关键定义。
| 参数 | 说明 |
|---|---|
ReportId |
创建的报表的全局唯一标识符 (UUID) |
ReportName |
在创建报表期间请求有效负载中提供的名称 |
Description |
在创建报表期间请求有效负载中提供的说明 |
QueryId |
在创建报表期间请求有效负载中提供的查询 ID |
Query |
将为此报表执行的查询文本 |
User |
用于创建报表的用户 ID |
CreatedTime |
创建报表时的 UTC 时间，格式如下：yyyy-MM-ddTHH:mm:ssZ |
ModifiedTime |
上次修改报表时的 UTC 时间，格式如下：yyyy-MM-ddTHH:mm:ssZ |
ExecuteNow |
在创建报表期间请求有效负载中提供的 ExecuteNow 参数 |
queryStartTime |
在创建报表期间请求有效负载中提供的查询开始时间。 仅当设置为“True”时才 ExecuteNow 适用 |
queryEndTime |
在创建报表期间请求有效负载中提供的查询结束时间。 仅当设置为“True”时才 ExecuteNow 适用 |
StartTime |
在创建报表期间请求有效负载中提供的开始时间 |
ReportStatus |
报表执行的状态。 可能的值为 Paused、Active 和 Inactive。 |
RecurrenceInterval |
在创建报表期间请求有效负载中提供的重复间隔 |
RecurrenceCount |
报告的剩余重复计数 |
CallbackUrl |
在创建报表期间请求有效负载中提供的回调 URL |
CallbackMethod |
在创建报表期间请求有效负载中提供的回调方法 |
Format |
在创建报表期间请求有效负载中提供的报表文件的格式 |
EndTime |
报表创建期间请求有效负载中提供的结束时间。 仅当设置为“True”时才 ExecuteNow 适用 |
TotalRecurrenceCount |
RecurrenceCount 在创建报表期间的请求有效负载中提供 |
nextExecutionStartTime |
下一次报表执行开始时的 UTC 时间戳 |
TotalCount |
Value 数组中的记录数 |
StatusCode |
结果代码。 可能的值为 200、400、401、403、500 |
message |
执行 API 后显示的状态消息 |
“获取报表执行”API
可以使用此方法并结合从“创建报表”API 收到的 ReportId 来查询报表执行的状态。 如果报表可供下载，该方法将返回报表下载链接。 否则，该方法返回状态。 还可以使用此 API 来获取给定报表发生的所有执行。
重要
此 API 设置的默认查询参数适用于 executionStatus=Completed 且 getLatestExecution=true 的情况。 因此，在首次成功执行报表之前调用该 API 会返回404。 可以通过设置 executionStatus=Pending 来获取挂起的执行。
请求语法
| 方法 | 请求 URI |
|---|---|
| 获取 | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution} |
请求标头
| 标头 | 类型 | 说明 |
|---|---|---|
| 授权 | 字符串 | 必需。 Microsoft Entra 访问令牌。 格式为 Bearer <token>。 |
| 内容类型 | string | application/json |
路径参数
无
查询参数
| 参数名称 | 必须 | 类型 | 说明 |
|---|---|---|---|
reportId |
是 | string | 通过筛选来仅获取具有此参数中指定的 reportId 的报表的执行详细信息。 |
executionId |
否 | string | 通过筛选来仅获取具有此参数中指定的 executionId 的报表的详细信息。 可以通过用分号“;”分隔多个值来指定多个 executionIds 。 |
executionStatus |
否 | 字符串/枚举 | 通过筛选来仅获取具有此参数中指定的 executionStatus 的报表的详细信息。有效值为 Pending、Running、Paused 和 Completed 默认值为 Completed。 |
getLatestExecution |
否 | boolean | 该 API 返回最新报表执行的详细信息。 默认情况下，此参数设置为 true。 如果选择将此参数的值作为 false 传递，该 API 将返回过去 90 天的执行实例。 |
请求有效负载
无
示例响应
响应有效负载的结构如下：
响应代码：200、400、401、403、404、500
响应有效负载示例：
{
"value": [
{
"executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
"reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
"recurrenceInterval": 4,
"recurrenceCount": 10,
"callbackUrl": null,
"format": "csv",
"executionStatus": "Completed",
"reportAccessSecureLink": "https://<path to report for download>",
"reportExpiryTime": null,
"reportGeneratedTime": "2021-01-13T14:40:46Z"
}
],
"totalCount": 1,
"message": null,
"statusCode": 200
}
报表执行完成后，将显示执行状态 Completed。 可以通过在 reportAccessSecureLink 中选择 URL 来下载报表。
术语表
响应中元素的关键定义。
| 参数 | 说明 |
|---|---|
ExecutionId |
执行实例的全局唯一标识符 (UUID) |
ReportId |
与执行实例关联的报表 ID |
RecurrenceInterval |
创建报表期间提供的重复间隔 |
RecurrenceCount |
创建报表期间提供的重复次数 |
CallbackUrl |
与执行实例关联的回调 URL |
CallbackMethod |
在创建报表期间请求有效负载中提供的回调方法 |
Format |
执行结束时生成的文件的格式 |
ExecutionStatus |
报表执行实例的状态。 有效值为 Pending、Running、Paused 和 Completed |
ReportLocation |
下载报表的位置。 |
ReportAccessSecureLink |
可用于安全地访问报表的链接 |
ReportExpiryTime |
报表链接过期的 UTC 时间，格式如下：yyyy-MM-ddTHH:mm:ssZ |
ReportGeneratedTime |
生成报表时的 UTC 时间，格式如下：yyyy-MM-ddTHH:mm:ssZ |
EndTime |
报表创建期间请求有效负载中提供的结束时间。 仅当设置为“True”时才 ExecuteNow 适用 |
TotalRecurrenceCount |
RecurrenceCount 在创建报表期间的请求有效负载中提供 |
nextExecutionStartTime |
下一次报表执行开始时的 UTC 时间戳 |
TotalCount |
值数组中的数据集数目 |
StatusCode |
结果代码 可能的值为 200、400、401、403、404 和 500 |
message |
执行 API 后显示的状态消息 |
后续步骤
- 可以通过 Swagger API URL 试用 API
- 对 Marketplace Insights 报表进行第一次 API 调用
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈