Note
Web IQ Commerce 以个人预览版提供给一组Azure客户。 在个人预览版期间,每 1,000 个 API 调用按 $7.00 计费。 API 图面和协定可能会更改。
符合条件的客户可以在 Web IQ 开发人员门户中的 Playground 中试用商务 API。 如果以前没有使用过 Playground,请从 快速入门开始。
我们将在个人预览版期间扩展访问权限;不保证访问。 若要请求访问或提问,请打开 Web IQ 支持请求,选择 “身份验证和访问 ”作为问题类型和 API 密钥设置 作为子类型,选择“ 创建支持请求”,并包括 AppID(从 Web IQ 开发人员门户中的配置文件管理复制它),或者,如果还没有,公司名称和 Web IQ 资源的名称。
Web IQ 商业 API 是 商务搜索、 套餐和 产品详细信息。 商务搜索返回产品查询的排名产品和卖家产品/服务。 将可用的产品、SKU 和产品/服务标识符与产品/服务一起使用。 产品详细信息接受产品和 SKU 标识符。
这三个终结点都接受 POST JSON 正文的请求。 使用标头中x-apikey为 Commerce 启用的 API 密钥或标头中的AuthorizationMicrosoft Entra ID访问令牌进行身份验证。 有关设置说明,请参阅 “身份验证 ”。
示例使用虚构的 Contoso 产品、卖家、标识符、URL 和价格。 在发出后续请求时,将示例标识符替换为商务搜索响应中的值。
请求标头
| 页眉 | 类型 | Description |
|---|---|---|
| x-apikey 或 授权 | 字符串 | API 密钥或Entra ID访问令牌进行身份验证。 |
| Content-Type | 字符串 | 请求正文的 MIME 类型。 使用 application/json。 |
支持的市场
在个人预览版期间,商务 API 支持这些组合 language 和 region。 不支持其他组合。
| 市场 | language |
region |
|---|---|---|
| 英语(美国) | en |
US |
| 西班牙语(美国) | es |
US |
| 英语(加拿大) | en |
CA |
| 法语(加拿大) | fr |
CA |
| 英语(英国) | en |
GB |
| 德语(德国) | de |
DE |
| 法语(法国) | fr |
FR |
| 英语(澳大利亚) | en |
AU |
| 日语(日本) | ja |
JP |
产品/服务链接和归属
对于你提供的每个产品/服务, clickUrl 请根据该响应中返回的每个链接或指向产品/服务的导航(无论是由用户还是代理用户代理的代理)使用。 默认情况下,clickUrl是Microsoft托管的重定向;Microsoft还可以返回直接商家 URL。 仅用于 displayUrl 在显示或模型上下文中标识商家或卖家,绝不是链接或导航目标。 如果产品/服务没有可用 clickUrl产品/服务,请不要提供产品/服务。
视为 clickUrl 不透明。 属性参数是必需的,并且可以位于重定向内部,因此它可能不可见。 请勿去除、重写、截断、解码或替换 clickUrl 或其属性参数,不要绕过重定向或自行添加参数。 仅当它通过未更改传递原始clickUrl链接时,才能包装clickUrl在自己的跟踪或重定向链接中。 不要重复使用 clickUrl 其他响应、查询、用户或目的,包括通过缓存。 最终用户自己的共享或转发不会重复使用。
从 clickUrl 响应中的应用程序代码中生成每个链接,而不是让模型重现它。 有关适用的条款,请参阅 Web IQ 使用条款的附录 B。
商务搜索
终结点:POST https://api.microsoft.ai/v3/search/commerce/products
返回产品查询的排名产品和卖家产品/服务。 将可用的产品、SKU 和产品/服务标识符与 产品/服务一起使用。 产品详细信息 接受产品和 SKU 标识符。
商务搜索示例请求
curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "Contoso wireless headphones",
"maxResults": 1,
"language": "en",
"region": "US",
"location": "lat:37.7749;long:-122.4194"
}'
商务搜索参数
| 参数 | Required | 类型 | Default | Description |
|---|---|---|---|---|
query |
Yes | 字符串 | - | 非空白的产品搜索查询。 最大长度为 1,000 个字符。 |
maxResults |
No | 整数 | 10 |
要返回的最大产品数,从 1 到 50。 |
language |
No | 字符串 | en |
双字母 ISO 639-1 结果语言。 请参阅 支持的市场。 |
region |
No | 字符串 | US |
双字母国家或地区代码。 请参阅 支持的市场。 |
location |
No | 字符串 | - |
lat:<latitude>;long:<longitude>位置格式,例如lat:37.7749;long:-122.4194。 纬度必须从 -90 到 90,经度必须从 -180 到 180。 |
商务搜索响应
返回一个 CommerceResponse ,其中包含排名 的产品 及其 产品/服务。 如果没有产品匹配,则响应为 200 OK 空 products 数组。
示例 200 OK 响应(摘录):
{
"products": [
{
"offers": [
{
"id": "100000000001",
"name": "Contoso Wireless Headphones",
"seller": {
"name": "Contoso Electronics",
"logoUrl": "https://contoso.example/logo.png"
},
"price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
}
],
"id": "PG_00000000000000000000000000000001",
"skuId": "00000000000000000000000000000001"
}
],
"traceId": "<trace-id>"
}
商务搜索错误
缺失、空白或过长query、超出范围maxResults、regionlanguage非两个字符或无效location的400返回(HandlerInvalidInput)。 服务故障返回 500 (InternalServerError)。 有关身份验证、授权、格式和配额错误,请参阅 错误。
商务搜索限制
-
query:1 到 1,000 个字符,而不仅仅是空格。 -
maxResults:1 到 50,默认值10。 返回的产品数取决于可用的匹配项。 没有分页,也没有每个产品的产品/服务数量的参数。 -
language和region:双字符代码。location坐标必须位于参数表中的范围内。 - 应用配置文件(AppID)的 速率限制和每日配额 也适用。
Offers
终结点:POST https://api.microsoft.ai/v3/fetch/commerce/products/offers
返回来自商务搜索的一个产品、SKU 或代表性产品/服务的合格卖家产品/服务。 它返回卖方产品/服务,而不是产品级反馈或价格历史记录。
产品/服务示例请求
curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/offers" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"productId": "PG_00000000000000000000000000000001",
"skuId": "00000000000000000000000000000001",
"offerId": "100000000001",
"language": "en",
"region": "US"
}'
产品/服务参数
从商务搜索响应中发送所选产品的所有可用产品、SKU 和产品/服务标识符。 如果只返回一个标识符,请发送该标识符。 至少需要一个不为空的标识符;无一个请求返回 400 (HandlerInvalidInput)。
| 参数 | Required | 类型 | Default | Description |
|---|---|---|---|---|
productId |
有條件的 | 字符串 | - | 商务搜索返回的产品 id 。 最多 1,000 个字符。 |
skuId |
有條件的 | 字符串 | - | 商务搜索返回的产品 skuId 。 最多 1,000 个字符。 |
offerId |
有條件的 | 字符串 | - | 商务搜索返回的代表产品/服务 id 。 最多 1,000 个字符。 |
language |
No | 字符串 | en |
双字母 ISO 639-1 结果语言。 请参阅 支持的市场。 |
region |
No | 字符串 | US |
双字母国家或地区代码。 请参阅 支持的市场。 |
location |
No | 字符串 | - |
lat:<latitude>;long:<longitude>格式的位置。 纬度必须从 -90 到 90,经度必须从 -180 到 180。 |
产品/服务响应
CommerceOffersResponse
| 领域 | 类型 | Description |
|---|---|---|
offers |
CommerceOffer 数组 | 主要或代表性产品/服务首先提供,然后是附加产品/服务。 |
traceId |
字符串 | 请求跟踪标识符进行调试和关联。 |
有关产品/服务字段,请参阅 CommerceOffer、 CommerceOfferImage、 CommerceInstallmentInfo 和支持 对象。 未知标识符使用空offers数组返回200 OK。
示例 200 OK 响应(摘录):
{
"offers": [
{
"id": "100000000001",
"name": "Contoso Wireless Headphones",
"seller": {
"name": "Contoso Electronics",
"logoUrl": "https://contoso.example/logo.png"
},
"price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
}
],
"traceId": "<trace-id>"
}
产品/服务错误
缺失或空白标识符、长度超过 1,000 个字符的标识符、languageregion不是两个字符的标识符或无效location的400返回(HandlerInvalidInput)。 未知标识符使用空offers数组返回200 OK。 服务故障返回 500 (InternalServerError)。 请参阅 错误。
产品/服务限制
- 每个请求一个产品、SKU 或代表产品/服务查找;不支持批处理查找。 每个标识符限制为 1,000 个字符。
- 没有
maxResults、偏移量或游标参数。 产品/服务的数量取决于可用性。 -
language和region:双字符代码。location坐标必须位于参数表中的范围内。 - 应用配置文件(AppID)的 速率限制和每日配额 也适用。
产品详细信息
终结点:POST https://api.microsoft.ai/v3/fetch/commerce/products/details
从商务搜索返回产品 ID、SKU ID 或两者的产品标题(name)、说明和聚合分级。 当可用时,将包含说明。
产品详细信息示例请求
curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/details" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"productId": "PG_00000000000000000000000000000002",
"skuId": "00000000000000000000000000000002",
"language": "en",
"region": "US"
}'
产品详细信息参数
至少需要一个 productId 或 skuId 不是空白,你可以发送这两者。
offerId 不是替代方法:只有产品/服务 ID 的请求无法通过验证。
| 参数 | Required | 类型 | Default | Description |
|---|---|---|---|---|
productId |
有條件的 | 字符串 | - | 来自商务搜索的产品 id 。 在未 skuId 发送时必需。 最多 1,000 个字符。 |
skuId |
有條件的 | 字符串 | - | 来自商务搜索的 SKU ID。 在未 productId 发送时必需。 最多 1,000 个字符。 |
language |
No | 字符串 | en |
双字母语言代码。 如果省略或 null使用默认值。 请参阅 支持的市场。 |
region |
No | 字符串 | US |
用于产品查找的双字母区域代码。 如果省略或 null使用默认值。 请参阅 支持的市场。 |
产品详细信息响应
CommerceProductDetailsResponse
| 领域 | 类型 | Description |
|---|---|---|
products |
CommerceProductDetails 数组 | 零个或一个匹配的产品。 不支持批处理查找。 |
traceId |
字符串 | 请求跟踪标识符。 |
CommerceProductDetails
| 领域 | 类型 | Description |
|---|---|---|
id |
字符串 | 跨变体的产品标识符,匹配商务搜索。 |
name |
字符串 | 产品标题(如果可用)。 |
description |
字符串 | 产品说明(如果可用)。 |
rating |
CommerceRating | 产品平均分级和分级计数(以 1 到 5 缩放)。 |
CommerceRating
当没有可用的分级时,将省略该 rating 对象。
| 领域 | 类型 | Description |
|---|---|---|
value |
number | 产品平均评分,舍入为两个小数位数。 |
scaleMin |
number | 分级比例的底部(1)。 |
scaleMax |
number | 分级比例(5) 的顶部。 |
count |
整数 | 产品的分级数。 返回零的计数。0 |
未知产品使用空products数组返回200 OK。
示例 200 OK 响应:
{
"products": [
{
"id": "PG_00000000000000000000000000000002",
"name": "Contoso Wireless Earbuds",
"description": "Illustrative wireless in-ear headphones",
"rating": { "value": 4.2, "scaleMin": 1, "scaleMax": 5, "count": 42 }
}
],
"traceId": "<trace-id>"
}
产品详细信息错误
缺少或空白的产品或 SKU 标识符、长度超过 1,000 个字符的标识符,或者languageregion不是两个字符返回400(HandlerInvalidInput)。 服务故障返回 500 (InternalServerError)。 请参阅 错误。
产品详细信息限制
- 至少一个产品或 SKU 标识符,每个标识符最多 1,000 个字符。 仅支持按产品/服务 ID 进行批量查找和查找。
-
language和region:双字符代码。 - 应用配置文件(AppID)的 速率限制和每日配额 也适用。
响应对象
这些对象由商务搜索和套餐返回。
CommerceResponse
| 领域 | 类型 | Description |
|---|---|---|
products |
CommerceProduct 数组 | 按排名顺序排列的产品。 |
traceId |
字符串 | 请求跟踪标识符进行调试和关联。 |
CommerceProduct
| 领域 | 类型 | Description |
|---|---|---|
id |
字符串 | 跨变体的产品标识符。 |
skuId |
字符串 | 目录 SKU 标识符。 |
offers |
CommerceOffer 数组 | 主要卖方产品/服务。 |
CommerceOffer
| 领域 | 类型 | Description |
|---|---|---|
id |
字符串 | 产品/服务标识符。 |
name |
字符串 | 卖家标题。 |
description |
字符串 | 卖家说明。 |
specifications |
数组 CommerceSpecification |
产品/服务级规范和所选属性。 保留重复项和源顺序。 请参阅 支持对象。 |
seller |
CommerceSeller |
商家详细信息。 请参阅 支持对象。 |
price |
CommerceOfferPrice |
ISO 4217 次要单位的产品/服务定价。
offeredPrice 当没有折扣价格时,回退到 listPrice 没有折扣价格。 请参阅 支持对象。 |
displayUrl |
字符串 | 仅限显示或模型上下文的商家或卖家 URL。 不要将其用作链接或导航目标。 |
clickUrl |
字符串 | 指向产品/服务的每个链接或导航的目标。 按返回的完全一样使用它。 请参阅 “产品/服务”链接和归属。 |
images |
CommerceOfferImage 数组 | 提供映像。 |
installmentInfo |
CommerceInstallmentInfo | 分期付款详细信息。 |
shippingInfo |
字符串 | 寄送信息,作为可读文本。 |
condition |
字符串 | 已提供商品的卖方提供条件。 |
CommerceOfferImage
| 领域 | 类型 | Description |
|---|---|---|
url |
字符串 | 图像 URL。 |
CommerceInstallmentInfo
| 领域 | 类型 | Description |
|---|---|---|
description |
字符串 | 分期付款计划的说明,作为可读文本。 |
downPayment |
CommercePrice |
需要提前支付的金额。 请参阅 支持对象。 |
monthlyPayment |
CommercePrice |
每月分期付款。 请参阅 支持对象。 |
months |
整数 | 月数。 |
支持对象
价格是 ISO 4217 货币次要单位的整数。 例如, 10000 值为 currencyUSD $100.00。
| Object | 领域 | 类型 | Description |
|---|---|---|---|
CommerceOfferPrice |
listPrice |
整数 | ISO 4217 次要单位的原始价格。 |
CommerceOfferPrice |
offeredPrice |
整数 | ISO 4217 次要单位的当前价格。 回退到 listPrice 没有折扣价格可用时。 |
CommerceOfferPrice |
currency |
字符串 | ISO 4217 货币代码。 |
CommercePrice |
amount |
整数 | ISO 4217 次要单位中的付款金额。 |
CommercePrice |
currency |
字符串 | ISO 4217 货币代码。 |
CommerceSeller |
name |
字符串 | 商家显示名称。 |
CommerceSeller |
logoUrl |
字符串 | 商家徽标 URL。 |
CommerceSpecification |
name |
字符串 | 产品/服务属性名称。 |
CommerceSpecification |
values |
字符串数组 | 属性显示值,保留重复项和源顺序。 |
Errors
这些错误适用于所有三个终结点。 每个终结点的验证和空结果行为在其自己的部分中介绍。
| HTTP 状态 | 错误代码 | 意义与行动 |
|---|---|---|
400 |
RequestInvalidFormat、HandlerInvalidInput |
格式不正确的 JSON 或请求参数缺失或无效。 使用终结点的参数表和限制更正请求。 |
401 |
身份验证错误,例如 AuthNoToken 或 AuthInvalidApiKey |
凭据缺失、无效或已过期。 再次使用有效凭据进行身份验证。 |
403 |
AuthUnauthorizedService |
调用方无权访问请求的资源。 如果未为 Commerce 启用应用配置文件,请请求访问,如此页面顶部所述。 |
405 |
MethodNotAllowed |
使用 POST,而不是 GET。 |
415 |
RequestUnsupportedMediaType |
发送 content-type: application/json。 |
429 |
AuthUserThrottled、AuthUserDailyUsageExceeded |
已超出应用配置文件(AppID)的速率限制或每日配额。 等待 retryAfter 重试前的时间。 |
500 |
InternalServerError |
服务无法完成请求。 在指示的延迟后重试,并在联系支持人员时包括 traceId 该重试。 |
错误响应
错误使用共享 错误响应结构。
| 领域 | 类型 | Description |
|---|---|---|
errorCode |
字符串 | 机器可读的错误代码。 |
errorCategory |
字符串 |
UserError 或 SystemError。 |
userMessage |
字符串 | 错误的可读说明。 |
technicalDetails |
字符串 | 可选诊断详细信息。 |
retryAfter |
字符串 | 可选的重试延迟(以秒为单位),后跟s后缀(例如)。 "60s" |
requestId |
字符串 | 可选请求标识符。 |
traceId |
字符串 | 用于支持的可选分布式跟踪标识符。 |
错误示例
不带 query: 的商务搜索请求:
curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{}'
400 Bad Request 响应:
{
"errorCode": "HandlerInvalidInput",
"errorCategory": "UserError",
"userMessage": "Invalid input provided. Please check your request parameters.",
"technicalDetails": "query is required",
"traceId": "<trace-id>"
}
速率限制
所有三个终结点都使用 Web IQ AppID(默认情况下每秒 15 个查询)的速率限制和每日配额,与 AppID 调用的其他 Web IQ API 共享。 响应429包括重试延迟。retryAfter 每日配额重置为 00:00 UTC。 有关重试指南,请参阅 错误处理。