你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
CustomInstanceExtensions.ImageSearchAsync 方法
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
自定义图像搜索 API 允许你向必应发送图像搜索查询，并获取在 Web 的自定义视图中找到的图像结果。
public static System.Threading.Tasks.Task<Microsoft.Azure.CognitiveServices.Search.CustomImageSearch.Models.Images> ImageSearchAsync (this Microsoft.Azure.CognitiveServices.Search.CustomImageSearch.ICustomInstance operations, string customConfig, string query, string acceptLanguage = default, string userAgent = default, string clientId = default, string clientIp = default, string location = default, string aspect = default, string color = default, string countryCode = default, int? count = default, string freshness = default, int? height = default, string id = default, string imageContent = default, string imageType = default, string license = default, string market = default, long? maxFileSize = default, long? maxHeight = default, long? maxWidth = default, long? minFileSize = default, long? minHeight = default, long? minWidth = default, long? offset = default, string safeSearch = default, string size = default, string setLang = default, int? width = default, System.Threading.CancellationToken cancellationToken = default);static member ImageSearchAsync : Microsoft.Azure.CognitiveServices.Search.CustomImageSearch.ICustomInstance * string * string * string * string * string * string * string * string * string * string * Nullable<int> * string * Nullable<int> * string * string * string * string * string * Nullable<int64> * Nullable<int64> * Nullable<int64> * Nullable<int64> * Nullable<int64> * Nullable<int64> * Nullable<int64> * string * string * string * Nullable<int> * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Azure.CognitiveServices.Search.CustomImageSearch.Models.Images><Extension()>
Public Function ImageSearchAsync (operations As ICustomInstance, customConfig As String, query As String, Optional acceptLanguage As String = Nothing, Optional userAgent As String = Nothing, Optional clientId As String = Nothing, Optional clientIp As String = Nothing, Optional location As String = Nothing, Optional aspect As String = Nothing, Optional color As String = Nothing, Optional countryCode As String = Nothing, Optional count As Nullable(Of Integer) = Nothing, Optional freshness As String = Nothing, Optional height As Nullable(Of Integer) = Nothing, Optional id As String = Nothing, Optional imageContent As String = Nothing, Optional imageType As String = Nothing, Optional license As String = Nothing, Optional market As String = Nothing, Optional maxFileSize As Nullable(Of Long) = Nothing, Optional maxHeight As Nullable(Of Long) = Nothing, Optional maxWidth As Nullable(Of Long) = Nothing, Optional minFileSize As Nullable(Of Long) = Nothing, Optional minHeight As Nullable(Of Long) = Nothing, Optional minWidth As Nullable(Of Long) = Nothing, Optional offset As Nullable(Of Long) = Nothing, Optional safeSearch As String = Nothing, Optional size As String = Nothing, Optional setLang As String = Nothing, Optional width As Nullable(Of Integer) = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of Images)参数
- operations
- ICustomInstance
此扩展方法的操作组。
- customConfig
- String
自定义搜索配置的标识符
- query
- String
用户的搜索查询词。 术语不能为空。 术语可能包含 必应高级运算符。 例如，若要将图像限制为特定域，请使用 site： 运算符。 为了帮助提高见解查询的相关性 (请参阅 insightsToken) ，应始终包含用户的查询词。 仅对图像搜索使用此参数 API.Do 调用热门图像 API 时不指定此参数。
- acceptLanguage
- String
用于用户界面字符串的一个或多个语言的逗号分隔列表。 此列表以降序方式显示首选项。 有关其他信息（包括预期格式），请参阅 RFC2616。 此标头和 setLang 查询参数互斥;不要同时指定两者。 如果设置此标头，则还必须指定 cc 查询参数。 为了确定要为其返回结果的市场，必应使用它从列表中找到的第一个受支持语言，并将其与 cc 参数值组合在一起。 如果列表不包括支持的语言，必应会查找最接近的语言和支持请求的市场，或将聚合或默认市场用于结果。 若要确定必应使用的市场，请查看 BingAPIs-Market 标头。 仅当指定多种语言时，才使用此标头和 cc 查询参数。 否则，请使用 mkt 和 setLang 查询参数。 用户界面字符串是用作用户界面中标签的字符串。 JSON 响应对象中有几个用户界面字符串。 响应对象中 Bing.com 属性的任何链接均将应用指定的语言。
- userAgent
- String
发出请求的用户代理。 必应使用用户代理为移动用户提供优化体验。 尽管是可选的，但还是建议始终指定此标头。 user-agent 应该是任何常用浏览器发送的字符串。 有关用户代理的信息，请参阅 RFC 2616。下面是用户代理字符串的示例。 Windows Phone：Mozilla/5.0 (兼容;MSIE 10.0;Windows Phone 8.0;Trident/6.0;IEMobile/10.0;手臂;触摸;诺基亚;Lumia 822) 。 Android：Mozilla / 5.0 (Linux;美国;Android 2.3.5;en - us;SCH - I500 Build / GINGERBREAD) AppleWebKit / 533.1 (KHTML;如 Gecko) 版本 / 4.0 Mobile Safari / 533.1。 iPhone：Mozilla / 5.0 (iPhone;CPU iPhone OS 6_1，如 Mac OS X) AppleWebKit / 536.26 (KHTML;如 Gecko) Mobile / 10B142 iPhone4;1 BingWeb / 3.03.1428.20120423。 电脑：Mozilla / 5.0 (Windows NT 6.3;WOW64;Trident / 7.0;触摸;rv：11.0) ，如 Gecko。 iPad：Mozilla / 5.0 (iPad;CPU OS 7_0，如 Mac OS X) AppleWebKit / 537.51.1 (KHTML，如 Gecko) Version / 7.0 Mobile / 11A465 Safari / 9537.53
- clientId
- String
必应使用此标头跨必应 API 调用为用户提供一致的行为。 必应通常会发布新功能和改进，并将客户端 ID 用作密钥以在不同航班上分配客流量。 如果未跨多个请求将相同的客户端 ID 用于用户，则必应可能将用户分配给多个冲突的航班。 分配给多个冲突航班可能导致用户体验不一致。 例如，如果第二个请求与第一个请求的航班分配不同，体验可能会出现意外。 此外，必应可以使用客户端 ID 根据客户端 ID 搜索历史记录来定制 Web 结果，为用户提供更丰富的体验。 通过分析由客户端 ID 生成的活动，必应还会使用此标头来提高结果排名。 相关改进有助于提高必应 API 交付的结果质量，从而提高 API 客户的点击率。 重要提示：尽管是可选的，但应将此标头视为必选。 对于同一最终用户和设备组合，如果跨多个请求保留客户端 ID，则 1) API 客户可以获取一致的用户体验；2) 可通过必应 API 提高结果质量，从而提高点击率。 在设备上使用你的应用程序的每个用户必须具有必应生成的唯一客户端 ID。 如果未在请求中包含此标头，必应会生成 ID，然后在 X-MSEdge-ClientID 响应标头中将其返回。 仅当用户首次在设备上使用应用时，才不可以在请求中包含此标头。 针对应用为设备上的此用户生成的每个必应 API 请求，使用客户端 ID。 保留客户端 ID。 若要在浏览器应用中保留 ID，请使用持久性 HTTP Cookie 来确保所有会话均使用此 ID。 请勿使用会话 Cookie。 对于移动应用等其他应用，请使用设备的持久存储来保留 ID。 下次用户在该设备上使用你的应用时，会获取保留的客户端 ID。 必应响应不一定包含此标头。 如果响应包含此标头，请针对该设备上的用户捕获客户端 ID 并将其用于所有后续必应请求。 如果包含 X-MSEdge-ClientID，不可在请求中包含 Cookie。
- clientIp
- String
客户端设备的 IPv4 或 IPv6 地址。 IP 地址用于发现用户的位置。 必应使用位置信息来确定安全搜索行为。 尽管是可选的，但还是建议始终指定此标头和 X-Search-Location 标头。 不要混淆地址（例如，通过将最后一个八位字节更改为 0 来混淆地址）。 混淆地址会导致位置未处于设备实际位置附近，这可能导致必应提供错误的结果。
- location
- String
以分号分隔的键/值对列表，描述客户端的地理位置。 必应使用位置信息来确定安全搜索行为并返回相关的本地内容。 以 <键>:<值> 形式指定键/值对。 下面是用于指定用户位置的键。 lat (所需的) ：客户端位置的纬度（以度为单位）。 纬度必须大于或等于 -90.0 且小于或等于 +90.0。 负值表示南纬，正值表示北纬。 long (必需) ：客户端位置的经度（以度为单位）。 经度必须大于或等于 -180.0 且小于或等于 +180.0。 负值表示西经，正值表示东经。 re (所需的) ：半径（以米为单位），指定坐标的水平精度。 传递设备定位服务返回的值。 典型的值可能是：22m - GPS/Wi-Fi、380m - 蜂窝基站三角网定位、18,000m - 反向 IP 查询。 ts (可选) ：客户端位于该位置时的 UTC UNIX 时间戳。 (UNIX 时间戳是自 1970 年 1 月 1 日以来的秒数。) 头 (可选) ：客户端的相对航向或行驶方向。 以度数指定旅行方向（从 0 到 360），相对于正北方向顺时针计数。 仅当 sp 键为非零时，才指定此键。 sp (可选) ：客户端设备正在行驶的水平速度 (速度) （以米/秒为单位）。 alt (可选) ：客户端设备的高度（以米为单位）。 (可选) ：半径（以米为单位），指定坐标的垂直精度。 仅当指定 alt 键时，才指定此键。 尽管许多键是可选的，但提供的信息越多，位置结果越精确。 尽管是可选的，但还是建议始终指定用户的地理位置。 如果客户端的 IP 地址未准确反映用户的物理位置（例如，如果客户端使用 VPN），则提供位置尤其重要。 为了获得最佳结果，应包含此标头和 X-MSEdge-ClientIP 标头，但应至少包含此标头。
- aspect
- String
按以下纵横比筛选图像。 全部：不按方面进行筛选。指定此值与不指定 aspect 参数相同。 方形：返回具有标准纵横比的图像。 宽：返回宽屏纵横比的图像。 高：返回高纵横比的图像。 可能的值包括：“All”、“Square”、“Wide”、“Tall”
- color
- String
按以下颜色选项筛选图像。 ColorOnly：返回彩色图像。 单色：返回黑白图像。 返回具有以下主导颜色之一的图像：黑色、蓝色、棕色、灰色、绿色、橙色、粉红色、紫色、红色、青色、白色、黄色。 可能的值包括：“ColorOnly”、“Monochrome”、“Black”、“Blue”、“Brown”、“Gray”、“Green”、“Orange”、“Pink”、“Purple”、“Red”、“Teal”、“White”、“Yellow”
- countryCode
- String
结果来源的国家/地区的 2 个字符国家/地区代码。 有关可能值的列表，请参阅 市场代码。 如果设置此参数，则还必须指定 Accept-language 标头。 必应使用从语言列表中找到的第一种受支持语言，并将该语言与指定的国家/地区代码组合在一起，以确定返回结果的市场。 如果语言列表不包含支持的语言，必应会查找支持请求的最近语言和市场，或者可能会对结果使用聚合市场或默认市场，而不是指定的市场。 仅当指定多种语言时，才应使用此查询参数和Accept-Language查询参数;否则，应使用 mkt 和 setLang 查询参数。 此参数和 mkt 查询参数相互排斥，不可同时指定两者。
响应中要返回的图像数。 提供的实际结果数可能小于请求获取的结果数。 默认值为 35。 最大值为 150。 将此参数与 offset 参数一起使用来对结果进行分页。例如，如果用户界面每页显示 20 个图像，请将 count 设置为 20，偏移量设置为 0 以获取结果的第一页。对于每个后续页，将偏移量递增 20 (例如 0、20、40) 。 仅对图像搜索使用此参数 API.Do 调用 Insights、Trending Images 或 Web 搜索 API 时不指定此参数。
- freshness
- String
按以下发现选项筛选图像。 日期：返回必应在过去 24 小时内发现的图像。 周：返回必应在过去 7 天内发现的图像。 月份：返回必应在过去 30 天内发现的图像。 可能的值包括：“Day”、“Week”、“Month”
- imageContent
- String
按以下内容类型筛选图像。 人脸：返回仅显示人脸的图像。 纵向：返回仅显示一个人的头部和肩膀的图像。 可能的值包括：“Face”、“Portrait”
- imageType
- String
按以下图像类型筛选图像。 AnimatedGif：仅返回动画 GIF。 剪贴画：仅返回剪贴画图像。 线条：仅返回线条图。 照片：仅返回 (的照片，不包括线条图、动态 Gif 和剪贴画) 。 购物：仅返回包含必应知道销售商品的商家的商品的图像。 此选项仅在 en - US 市场中有效。透明：仅返回具有透明背景的图像。 可能的值包括：“AnimatedGif”、“Clipart”、“Line”、“Photo”、“Shopping”、“Transparent”
- license
- String
按以下许可证类型筛选映像。 全部：不要按许可证类型进行筛选。指定此值与不指定许可证参数相同。 Any：返回任何许可证类型下的图像。 响应不包括未指定许可证或许可证未知的图像。 公开：在法律允许的最大范围内，返回创作者放弃其专有权的图像。 共享：返回可能与他人共享的图像。 可能不允许更改或编辑图像。 此外，可能不允许出于商业目的修改、共享和使用映像。 通常，此选项返回的图像最多。 ShareCommercially：返回可能出于个人或商业目的与他人共享的图像。 可能不允许更改或编辑图像。 修改：返回可以修改、共享和使用的图像。 可能不允许更改或编辑图像。 可能不允许出于商业目的修改、共享和使用映像。 ModifyCommercily：返回可能修改、共享和用于个人或商业目的的图像。 通常，此选项返回最少的图像。 有关这些许可证类型的详细信息，请参阅 按许可证类型筛选映像。 可能的值包括：“All”、“Any”、“Public”、“Share”、“ShareCommercially”、“Modify”、“ModifyCommercially”
- market
- String
产生结果的市场。 通常，mkt 是用户发出请求的国家/地区。 但是，如果用户不位于必应提供结果的国家/地区，则可能是不同的国家/地区。 市场必须采用语言代码>-国家/<地区代码>的形式<。 例如，en-US。 字符串不区分大小写。 有关可能的市场值的列表，请参阅 市场代码。 注意：如果已知，建议始终指定市场。 指定市场有助于必应路由请求，并返回适当的最佳响应。 如果指定的市场未在 市场代码中列出，必应会根据可能会更改的内部映射使用最适合的市场代码。 此参数和 cc 查询参数相互排斥，不可同时指定两者。
筛选小于或等于指定文件大小的图像。 可以指定的最大文件大小为 520，192 字节。 如果指定更大的值，API 将使用 520，192。 响应可能包含略大于指定最大值的图像。 可以指定此筛选器和 minFileSize 来筛选文件大小范围内的图像。
筛选高度小于或等于指定高度的图像。 指定高度（以像素为单位）。 可以指定此筛选器和 minHeight 来筛选高度范围内的图像。 此筛选器和高度筛选器是互斥的。
筛选宽度小于或等于指定宽度的图像。 指定宽度（以像素为单位）。 可以指定此筛选器和 maxWidth 来筛选宽度范围内的图像。 此筛选器和宽度筛选器是互斥的。
筛选大于或等于指定文件大小的图像。 可以指定的最大文件大小为 520，192 字节。 如果指定更大的值，API 将使用 520，192。 响应可能包含略小于指定最小值的图像。 可以指定此筛选器和 maxFileSize 来筛选文件大小范围内的图像。
筛选高度大于或等于指定高度的图像。 指定高度（以像素为单位）。 可以指定此筛选器和 maxHeight 来筛选高度范围内的图像。 此筛选器和高度筛选器是互斥的。
筛选宽度大于或等于指定宽度的图像。 指定宽度（以像素为单位）。 可以指定此筛选器和 maxWidth 来筛选宽度范围内的图像。 此筛选器和宽度筛选器是互斥的。
从零开始的偏移量，指示返回图像之前要跳过的图像数。 默认值为 0。 偏移量应小于 totalEstimatedMatches (
- count) 。 使用此参数和 count 参数对结果进行分页。 例如，如果用户界面每页显示 20 个图像，请将 count 设置为 20，偏移量设置为 0 以获取结果的第一页。 对于每个后续页，将偏移量递增 20 (例如 0、20、40) 。 多个页面可能在结果中包含一些重叠。 若要防止重复，请参阅 nextOffset。 仅对图像 API 使用此参数。 调用趋势图像 API 或 Web 搜索 API 时，请勿指定此参数。
- safeSearch
- String
筛选成人内容的图像。 下面是可能的筛选器值。 关闭：可能返回包含成人内容的图像。 如果请求通过图像搜索 API，则响应包括清晰 (非模糊) 的缩略图。 但是，如果请求通过 Web 搜索 API，则响应将包括像素化 (模糊) 的缩略图。 中等：如果请求通过图像搜索 API，则响应不包括包含成人内容的图像。 如果请求通过 Web 搜索 API，则响应可能包含包含成人内容的图像， (缩略图 (模糊) ) 像素化。 严格：不返回包含成人内容的图像。 默认级别为“中等”。 如果请求来自必应成人策略要求将 safeSearch 设置为 Strict 的市场，必应将忽略 safeSearch 值并使用 Strict。 如果使用 site： query 运算符，则无论 safeSearch 查询参数设置为什么，响应都可能包含成人内容。 使用网站：仅当你知道网站上的内容，并且你的方案支持成人内容的可能性时。 可能的值包括：“Off”、“Moderate”、“Strict”
- size
- String
按以下大小筛选图像。 全部：不要按大小进行筛选。 指定此值与不指定 size 参数相同。 小：返回小于 200x200 像素的图像。 中：返回大于或等于 200x200 像素但小于 500x500 像素的图像。 大：返回 500x500 像素或更大的图像。 壁纸：返回壁纸图像。 可以将此参数与高度或宽度参数一起使用。 例如，可以使用高度和大小来请求高度为 150 像素的小图像。 可能的值包括：“All”、“Small”、“Medium”、“Large”、“Wallpaper”
- setLang
- String
可用于用户界面字符串的语言。 使用 ISO 639-1 2 字母语言代码指定语言。 例如，英语的语言代码是 EN。 默认为 EN（英语）。 尽管是可选项，但应始终指定语言。 通常，将 setLang 设置为 mkt 指定的同一语言，除非用户希望用户界面字符串以其他语言显示。 此参数和 Accept-Language 标头互斥;不要同时指定两者。 用户界面字符串是用作用户界面中标签的字符串。 JSON 响应对象中有几个用户界面字符串。 此外，响应对象中 Bing.com 属性的任何链接均会应用指定的语言。
- cancellationToken
- CancellationToken
取消标记。
返回
适用于
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈