自訂和建議影像搜尋查詢

發行項
01/05/2022

警告

2020 年 10 月 30 日，Bing 搜尋 API 已從 Azure AI 服務移至Bing 搜尋服務。本文件僅供參考之用。如需更新的文件，請參閱 Bing 搜尋 API 文件。如需針對 Bing 搜尋建立新 Azure 資源的指示，請參閱透過 Azure Marketplace 建立 Bing 搜尋資源 \(英文\)。

使用本文來了解如何自訂查詢，以及建議要傳送至 Bing 影像搜尋 API 的搜尋字詞。

建議搜尋字詞

如果您的應用程式有用來輸入搜尋字詞的搜尋方塊，您可以使用Bing 自動建議 API 來改善體驗。 API 會即時顯示建議的搜尋字詞。 API 會根據部分搜尋字詞和 Azure AI 服務傳回建議的查詢字串。

樞紐分析查詢

如果 Bing 可以分割原始搜尋查詢，則傳回的 Images 物件會包含 pivotSuggestions 欄位。樞紐分析建議能以選用搜尋字詞的形式向使用者呈現。例如，如果原始查詢為 Microsoft Surface，則 Bing 可能會將查詢分割為 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 欄位包含原始查詢細分成的區段 (樞紐) 清單。對於每個樞紐，回應會包含一份查詢物件清單，其中包含建議的查詢。 text 欄位包含建議的查詢。 displayText 欄位包含的字詞可取代原始查詢中的樞紐分析。例如 Surface 的發行日期。

如果樞紐查詢字串就是使用者所要尋找的內容，您可以使用 text 和 thumbnail 欄位對使用者顯示樞紐查詢字串。使用 webSearchUrl URL 或 searchLink URL，讓縮圖和文字可以點選。使用 webSearchUrl 將使用者傳送給 Bing 搜尋結果。如果您提供的是自己的結果頁面，請使用 searchLink。

擴展查詢

如果 Bing 可以擴展查詢來縮小原始搜尋範圍，則 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 將使用者傳送給 Bing 搜尋結果。如果您提供的是自己的結果頁面，請使用 searchLink。

節流要求

服務與您的訂用帳戶類型將決定您所適用的每秒查詢數目 (QPS)。請確定您的應用程式包含維持在配額範圍內所需的邏輯。如果已達到或超過 QPS 限制，要求即會失敗，且會傳回 HTTP 429 狀態碼。回應會包含 Retry-After 標頭，指出您必須等待多久後才能傳送另一個要求。

拒絕服務與節流

服務會區分拒絕服務 (DoS) 攻擊和 QPS 違規。如果服務懷疑有 DoS 攻擊，要求仍會成功 (HTTP 狀態碼為「200 確定」)，但回應本文會是空的。

下一步

如果您從未試用過 Bing 影像搜尋 API，請透過快速入門試用此功能。如果您想要尋找更複雜的內容，請嘗試可建立單頁 Web 應用程式的教學課程。

共用方式為