商业 REST API 参考(个人预览版)

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。 有关重试指南,请参阅 错误处理。