Bing Image Search API v7 のアップグレード ガイドBing Image Search API v7 upgrade guide

このアップグレード ガイドでは、Bing Image Search API のバージョン 5 とバージョン 7 の間の変更点を示します。This upgrade guide identifies the changes between version 5 and version 7 of the Bing Image Search API. このガイドは、バージョン 7 を使用するために更新する必要のあるアプリケーションの部分を識別するのに役立ちます。Use this guide to help you identify the parts of your application that you need to update to use version 7.

重大な変更Breaking changes

エンドポイントEndpoints

  • エンドポイントのバージョン番号は、v5 から v7 に変更されました。The endpoint's version number changed from v5 to v7. たとえば、https://api.cognitive.microsoft.com/bing/**v7.0**/images/search のようになっています。For example, https://api.cognitive.microsoft.com/bing/**v7.0**/images/search.

エラー応答オブジェクトとエラー コードError response objects and error codes

  • すべての失敗した要求には、応答本文内に ErrorResponse オブジェクトが含まれるようになりました。All failed requests should now include an ErrorResponse object in the response body.

  • Error オブジェクトに次のフィールドが追加されました。Added the following fields to the Error object.

    • subCode—エラー コードを別個のバケットに分割します (可能な場合)subCode—Partitions the error code into discrete buckets, if possible
    • moreDetailsmessage フィールドで説明されているエラーに関する追加情報moreDetails—Additional information about the error described in the message field
  • v5 エラー コードを次の可能な code および subCode 値に置き換えました。Replaced the v5 error codes with the following possible code and subCode values.

コードCode サブコードSubCode 説明Description
ServerErrorServerError UnexpectedErrorUnexpectedError
ResourceErrorResourceError
NotImplementedNotImplemented
サブコード条件のいずれかが発生するたびに、Bing は ServerError を返します。Bing returns ServerError whenever any of the sub-code conditions occur. HTTP 状態コードが 500 の場合、応答にはこれらのエラーが含まれます。The response includes these errors if the HTTP status code is 500.
InvalidRequestInvalidRequest ParameterMissingParameterMissing
ParameterInvalidValueParameterInvalidValue
HttpNotAllowedHttpNotAllowed
BlockedBlocked
要求の一部が有効でない場合に Bing は InvalidRequest を返します。Bing returns InvalidRequest whenever any part of the request is not valid. たとえば、必要なパラメーターが不足している場合や、パラメーター値が無効な場合です。For example, a required parameter is missing or a parameter value is not valid.

エラーが ParameterMissing または ParameterInvalidValue の場合、HTTP 状態コードは 400 です。If the error is ParameterMissing or ParameterInvalidValue, the HTTP status code is 400.

エラーが HttpNotAllowed の場合、HTTP 状態コードは 410 です。If the error is HttpNotAllowed, the HTTP status code 410.
RateLimitExceededRateLimitExceeded 1 秒あたりのクエリ数 (QPS) または 1 か月あたりのクエリ数 (QPM) のクォータを超えると、Bing は RateLimitExceeded を返します。Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota.

QPS を超えた場合、Bing は HTTP 状態コード 429 を返し、QPM を超過した場合に 403 を返します。Bing returns HTTP status code 429 if you exceeded QPS and 403 if you exceeded QPM.
InvalidAuthorizationInvalidAuthorization AuthorizationMissingAuthorizationMissing
AuthorizationRedundancyAuthorizationRedundancy
Bing は、呼び出し元を認証できない場合に InvalidAuthorization を返します。Bing returns InvalidAuthorization when Bing cannot authenticate the caller. たとえば、Ocp-Apim-Subscription-Key ヘッダーがない場合や、サブスクリプション キーが無効な場合です。For example, the Ocp-Apim-Subscription-Key header is missing or the subscription key is not valid.

冗長性は、複数の認証方法を指定した場合に発生します。Redundancy occurs if you specify more than one authentication method.

エラーが InvalidAuthorization の場合、HTTP 状態コードは 401 です。If the error is InvalidAuthorization, the HTTP status code is 401.
InsufficientAuthorizationInsufficientAuthorization AuthorizationDisabledAuthorizationDisabled
AuthorizationExpiredAuthorizationExpired
呼び出し元がリソースに対するアクセス許可を備えていない場合、Bing は InsufficientAuthorization を返します。Bing returns InsufficientAuthorization when the caller does not have permissions to access the resource. これは、サブスクリプション キーが無効になっているか、期限が切れている場合に発生することがあります。This can occur if the subscription key has been disabled or has expired.

エラーが InsufficientAuthorization の場合、HTTP 状態コードは 403 です。If the error is InsufficientAuthorization, the HTTP status code is 403.
  • 以前のエラー コードと新しいコードのマッピングを次に示します。The following maps the previous error codes to the new codes. v5 エラー コードに依存していた場合は、コードを適宜更新してください。If you've taken a dependency on v5 error codes, update your code accordingly.
バージョン 5 コードVersion 5 code バージョン 7 コード.サブコードVersion 7 code.subCode
RequestParameterMissingRequestParameterMissing InvalidRequest.ParameterMissingInvalidRequest.ParameterMissing
RequestParameterInvalidValueRequestParameterInvalidValue InvalidRequest.ParameterInvalidValueInvalidRequest.ParameterInvalidValue
ResourceAccessDeniedResourceAccessDenied InsufficientAuthorizationInsufficientAuthorization
ExceededVolumeExceededVolume RateLimitExceededRateLimitExceeded
ExceededQpsLimitExceededQpsLimit RateLimitExceededRateLimitExceeded
DisabledDisabled InsufficientAuthorization.AuthorizationDisabledInsufficientAuthorization.AuthorizationDisabled
UnexpectedErrorUnexpectedError ServerError.UnexpectedErrorServerError.UnexpectedError
DataSourceErrorsDataSourceErrors ServerError.ResourceErrorServerError.ResourceError
AuthorizationMissingAuthorizationMissing InvalidAuthorization.AuthorizationMissingInvalidAuthorization.AuthorizationMissing
HttpNotAllowedHttpNotAllowed InvalidRequest.HttpNotAllowedInvalidRequest.HttpNotAllowed
UserAgentMissingUserAgentMissing InvalidRequest.ParameterMissingInvalidRequest.ParameterMissing
NotImplementedNotImplemented ServerError.NotImplementedServerError.NotImplemented
InvalidAuthorizationInvalidAuthorization InvalidAuthorizationInvalidAuthorization
InvalidAuthorizationMethodInvalidAuthorizationMethod InvalidAuthorizationInvalidAuthorization
MultipleAuthorizationMethodMultipleAuthorizationMethod InvalidAuthorization.AuthorizationRedundancyInvalidAuthorization.AuthorizationRedundancy
ExpiredAuthorizationTokenExpiredAuthorizationToken InsufficientAuthorization.AuthorizationExpiredInsufficientAuthorization.AuthorizationExpired
InsufficientScopeInsufficientScope InsufficientAuthorizationInsufficientAuthorization
BlockedBlocked InvalidRequest.BlockedInvalidRequest.Blocked

クエリ パラメーターQuery parameters

  • modulesRequested クエリ パラメーターの名前が modules に変更されました。Renamed the modulesRequested query parameter to modules.

  • Annotations の名前が Tags に変更されました。Renamed the Annotations to Tags. Tags に対する modules クエリ パラメーターについての説明を参照してください。See modules query parameter to Tags.

  • ShoppingSources フィルター値をサポートしている市場の一覧が、en-US のみに変更されました。Changed the list of supported markets of the ShoppingSources filter value to en-US only. imageType に関する説明を参照してください。See imageType.

イメージの分析情報の変更Image insights changes

  • ImagesInsightsannotations フィールドの名前が imageTags に変更されました。Renamed the annotations field of ImagesInsights to imageTags.

  • AnnotationModule オブジェクトの名前が ImageTagsModule に変更されました。Renamed the AnnotationModule object to ImageTagsModule.

  • Annotation オブジェクトの名前が Tag に変更され、confidence フィールドが削除されました。Renamed the Annotation object to Tag, and removed the confidence field.

  • Image オブジェクトの insightsSourcesSummary フィールドの名前が insightsMetadata に変更されました。Renamed the insightsSourcesSummary field of the Image object to insightsMetadata.

  • InsightsSourcesSummary オブジェクトの名前が InsightsMetadata に変更されました。Renamed the InsightsSourcesSummary object to InsightsMetadata.

  • https://api.cognitive.microsoft.com/bing/v7.0/images/details エンドポイントが追加されました。Added the https://api.cognitive.microsoft.com/bing/v7.0/images/details endpoint. イメージの分析情報を要求するときは、/images/search エンドポイントの代わりにこのエンドポイントを使用します。Use this endpoint to request image insights instead of the /images/search endpoint. Image Insights に関する説明を参照してください。See Image Insights.

  • 次のクエリ文字列パラメーターは、/images/details エンドポイントでのみ有効となりました。The following query parameters are now valid only with the /images/details endpoint.

  • ImageInsightsResponse オブジェクトの名前が ImageInsights に変更されました。Renamed the ImageInsightsResponse object to ImageInsights.

  • ImageInsights オブジェクト内の次のフィールドのデータ型が変更されました。Changed the data types of the following fields in the ImageInsights object.

    • relatedCollections フィールドの型が ImageGallery[] から RelatedCollectionsModule に変更されました。Changed the type of the relatedCollections field from ImageGallery[] to RelatedCollectionsModule.

    • pagesIncluding フィールドの型が Image[] から ImagesModule に変更されました。Changed the type of the pagesIncluding field from Image[] to ImagesModule.

    • relatedSearches フィールドの型が Query[] から RelatedSearchesModule に変更されました。Changed the type of the relatedSearches field from Query[] to RelatedSearchesModule.

    • recipes フィールドの型が Recipe[] から RecipesModule に変更されました。Changed the type of the recipes field from Recipe[] to RecipesModule.

    • visuallySimilarImages フィールドの型が Image[] から ImagesModule に変更されました。Changed the type of the visuallySimilarImages field from Image[] to ImagesModule.

    • visuallySimilarProducts フィールドの型が ProductSummaryImage[] から ImagesModule に変更されました。Changed the type of the visuallySimilarProducts field from ProductSummaryImage[] to ImagesModule.

    • ProductSummaryImage オブジェクトが削除され、製品関連のフィールドが Image オブジェクトに移動されました。Removed the ProductSummaryImage object and moved the product-related fields into the Image object. Image オブジェクトに製品関連のフィールドが含まれるのは、イメージ分析情報の応答で、イメージが、視覚的に類似した製品の一部として含まれている場合のみです。The Image object includes the product-related fields only when the image is included as part of visually similar products in an image insight response.

    • recognizedEntityGroups フィールドの型が RecognizedEntityGroup[] から RecognizedEntitiesModule に変更されました。Changed the type of the recognizedEntityGroups field from RecognizedEntityGroup[] to RecognizedEntitiesModule.

  • ImageInsightscategoryClassification フィールドの名前が annotations に変更され、型が AnnotationsModule に変更されました。Renamed the categoryClassification field of ImageInsights to annotations, and changed its type to AnnotationsModule.

イメージの応答Images answer

  • Images から displayShoppingSourcesBadges フィールドと displayRecipeSourcesBadges フィールドが削除されました。Removed the displayShoppingSourcesBadges and displayRecipeSourcesBadges fields from Images.

  • ImagesnextOffsetAddCount フィールドの名前が nextOffset に変更されました。Renamed the nextOffsetAddCount field of Images to nextOffset. オフセットの使用方法も変更されています。The way you use the offset has also changed. 以前は、offset クエリ パラメーターを nextOffsetAddCount の値、前の offset の値、および結果内のイメージ数の合計に設定していましたが、Previously, you set the offset query parameter to the nextOffsetAddCount value plus the previous offset value plus the number of images in the result. offsetnextOffset の値に設定するようになりました。Now, you set offset to the nextOffset value.

非破壊的変更Non-breaking changes

クエリ パラメーターQuery parameters

  • imageType フィルターに使用可能な値として、Transparent が追加されました。Added Transparent as a possible imageType filter value. Transparent フィルターは、透明な背景を持つイメージのみを返します。The Transparent filter returns only images with a transparent background.

  • license フィルターに使用可能な値として、Any が追加されました。Added the Any as a possible license filter value. Any フィルターは、ライセンスを受けているイメージのみを返します。The Any filter returns only images that are under license.

  • maxFileSize および minFileSize クエリ パラメーターが追加されました。Added the maxFileSize and minFileSize query parameters. これらのフィルターを使用すると、ファイル サイズが範囲内であるイメージが返されます。Use these filters to return images within a range of file sizes.

  • maxHeightminHeightmaxWidthminWidth の各クエリ パラメーターが追加されました。Added the maxHeight, minHeight, maxWidth, minWidth query parameters. これらのフィルターを使用すると、高さと幅が範囲内であるイメージが返されます。Use these filters to return images within a range of heights and widths.

オブジェクトの変更Object changes

  • Offer オブジェクトに description フィールドと lastUpdated フィールドが追加されました。Added the description and lastUpdated fields to the Offer object.

  • ImageGallery オブジェクトに name フィールドが追加されました。Added the name field to the ImageGallery object.

  • Images オブジェクトに similarTerms フィールドが追加されました。Added similarTerms to the Images object. このフィールドには、ユーザーのクエリ文字列と意味的に類似している用語のリストが含まれます。This field contains a list of terms that are similar in meaning to the user's query string.