自定义图像搜索查询并提供建议

项目
01/05/2022

警告

2020 年 10 月 30 日，必应搜索 API 从 Azure AI 服务迁移到必应搜索服务。本文档仅供参考。有关更新的文档，请参阅必应搜索 API 文档。关于为必应搜索创建新的 Azure 资源的说明，请参阅通过 Azure 市场创建必应搜索资源。

通过本文了解如何自定义查询并提供搜索词建议，以发送到必应图像搜索 API。

提供搜索词建议

如果应用有一个可以在其中输入搜索词的搜索框，则可使用必应自动推荐 API 来改进体验。该 API 可以实时显示建议的搜索词。 API 根据部分搜索词和 Azure AI 服务返回建议的查询字符串。

分段查询

如果必应可以将原始搜索查询分段，则返回的 Images 对象会包含 pivotSuggestions。分段建议可以作为可选搜索词向用户显示。例如，如果原始查询为 Microsoft Surface，则必应可能会将查询分成 Microsoft 和 Surface，并为每个拆分项提供建议的分段。这些建议可以作为可选查询词向用户显示。

以下示例演示了针对 Microsoft Surface 的分段建议：

{
    "_type": "Images",
    "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=microsoft%20surface&FORM=OIIARP",
    "totalEstimatedMatches": 1000,
    "value": [...],
    "queryExpansions": [...],
    "pivotSuggestions": [{
        "pivot": "microsoft",
        "suggestions": [{
            "text": "Contoso Surface",
            "displayText": "Contoso",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=OtterBox+Surface&FORM=IRQBPS",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=Contoso...",
                    "searchLink": "https:\/\/api.cognitive.microsoft.com\/api...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Contoso+Surface..."
            }
        },
        {
            "text": "Adatum Surface",
            "displayText": "Adatum",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Adatum+Surface&FORM=IRQBPS",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Adatum+Surface&pid=Ap..."
            }
        },
        ...
        ]
    },
    {
        "pivot": "surface",
        "suggestions": [{
            "text": "Microsoft Surface4",
            "displayText": "Surface4",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface...",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft..."
            }
        },
        {
            "text": "Microsoft Tablet",
            "displayText": "Tablet",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Tablet&FORM=IRQBPS",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Microsoft+Tablet..."
            }
        },
        ...
    ],
    "nextOffsetAddCount": 0
}

pivotSuggestions 字段包含将原始查询分成的段的列表。每个段的响应包含一个 Query 对象的列表，该对象包含建议的查询。 text 字段包含建议的查询。 displayText 字段包含替换原始查询中的分段的词。例如，“Surface 的发布日期”。

如果分段查询字符串是用户要查找的内容，请使用 text 和 thumbnail 字段显示分段查询字符串。使用 webSearchUrl URL 或 searchLink URL，使缩略图和文本可供用户单击。使用 webSearchUrl 将用户发送到必应搜索结果。如果提供自己的结果页面，请使用 searchLink。

扩展查询

如果必应可以通过扩展查询来缩小原始搜索的范围，则 Images 对象会包含 queryExpansions 字段。例如，如果查询为 Microsoft Surface，则扩展的查询可能为：

Microsoft Surface Pro 3。
Microsoft Surface RT。
Microsoft Surface Phone。
Microsoft Surface Hub。

以下示例演示了 Microsoft Surface 的扩展查询。

{
    "_type": "Images",
    "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=microsoft%20surface...",
    "totalEstimatedMatches": 1000,
    "value": [...],
    "queryExpansions":  [{
        "text": "Microsoft Surface Pro 3",
        "displayText": "Pro 3",
        "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+Pro+3...",
        "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=Microsoft...",
        "thumbnail": {
            "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+Pro+3..."
        }
    },
    {
        "text": "Microsoft Surface RT",
        "displayText": "RT",
        "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+RT...",
        "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",
        "thumbnail": {
            "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+RT..."
        }
    },
    {
        "text": "Microsoft Surface Phone",
        "displayText": "Phone",
        "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+Phone",
        "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",
        "thumbnail": {
            "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+Phone..."
        }
    }],
    "pivotSuggestions": [...],
    "nextOffsetAddCount": 0
}

queryExpansions 字段包含 Query 对象的列表。 text 字段包含扩展的查询。 displayText 字段包含扩展词。如果扩展的查询字符串是用户要查找的内容，请使用 text 和 thumbnail 字段显示扩展的查询字符串。使用 webSearchUrl URL 或 searchLink URL，使缩略图和文本可供用户单击。使用 webSearchUrl 将用户发送到必应搜索结果。如果提供自己的结果页面，请使用 searchLink。

限制请求

服务和订阅类型决定了每秒可以发出的查询数 (QPS)。请确保应用程序包含防止超出配额限制的逻辑。如果达到或超出 QPS 限制，则请求会失败，系统会返回 HTTP 429 状态代码。响应包含 Retry-After 标头，该标头指示需等待多久才能发送另一请求。

拒绝服务与限制

该服务区分拒绝服务 (DoS) 攻击和 QPS 违规。如果该服务怀疑存在 DoS 攻击，则请求会成功（HTTP 状态代码为“200 正常”）。但是，响应正文为空。

后续步骤

如果从未尝试过必应图像搜索 API，请尝试快速入门。如果需要更复杂的内容，请尝试关于如何创建单页 Web 应用的教程。

通过