Bing Image Search API v7 のアップグレード ガイド
警告
2020 年 10 月 30 日に、Bing Search API は Azure AI サービスから Bing Search サービスに移行されました。 このドキュメントは、参考用としてのみ提供されています。 更新されたドキュメントについては、Bing search API のドキュメントを参照してください。 Bing 検索用の新しい Azure リソースを作成する手順については、Azure Marketplace からの Bing Search リソースの作成に関するページを参照してください。
このアップグレード ガイドでは、Bing Image Search API のバージョン 5 とバージョン 7 の間の変更点を示します。 このガイドは、バージョン 7 を使用するために更新する必要のあるアプリケーションの部分を識別するのに役立ちます。
重大な変更
エンドポイント
- エンドポイントのバージョン番号は、v5 から v7 に変更されました。 たとえば、https://api.cognitive.microsoft.com/bing/**v7.0**/images/search となります。
エラー応答オブジェクトとエラー コード
すべての失敗した要求には、応答本文内に
ErrorResponseオブジェクトが含まれるようになりました。Errorオブジェクトに次のフィールドが追加されました。subCode—エラー コードを別個のバケットに分割します (可能な場合)moreDetails—messageフィールドで説明されているエラーに関する追加情報
v5 エラー コードを次の可能な
codeおよびsubCode値に置き換えました。
| コード | サブコード | 説明 |
|---|---|---|
| ServerError | UnexpectedError ResourceError NotImplemented |
サブコード条件のいずれかが発生するたびに、Bing は ServerError を返します。 HTTP 状態コードが 500 の場合、応答にはこれらのエラーが含まれます。 |
| InvalidRequest | ParameterMissing ParameterInvalidValue HttpNotAllowed Blocked |
要求の一部が有効でない場合に Bing は InvalidRequest を返します。 たとえば、必要なパラメーターが不足している場合や、パラメーター値が無効な場合です。 エラーが ParameterMissing または ParameterInvalidValue の場合、HTTP 状態コードは 400 です。 エラーが HttpNotAllowed の場合、HTTP 状態コードは 410 です。 |
| RateLimitExceeded | 1 秒あたりのクエリ数 (QPS) または 1 か月あたりのクエリ数 (QPM) のクォータを超えると、Bing は RateLimitExceeded を返します。 QPS を超えた場合、Bing は HTTP 状態コード 429 を返し、QPM を超過した場合に 403 を返します。 |
|
| InvalidAuthorization | AuthorizationMissing AuthorizationRedundancy |
Bing は、呼び出し元を認証できない場合に InvalidAuthorization を返します。 たとえば、Ocp-Apim-Subscription-Key ヘッダーがない場合や、サブスクリプション キーが無効な場合です。冗長性は、複数の認証方法を指定した場合に発生します。 エラーが InvalidAuthorization の場合、HTTP 状態コードは 401 です。 |
| InsufficientAuthorization | AuthorizationDisabled AuthorizationExpired |
呼び出し元がリソースに対するアクセス許可を備えていない場合、Bing は InsufficientAuthorization を返します。 これは、サブスクリプション キーが無効になっているか、期限が切れている場合に発生することがあります。 エラーが InsufficientAuthorization の場合、HTTP 状態コードは 403 です。 |
- 以前のエラー コードと新しいコードのマッピングを次に示します。 v5 エラー コードに依存していた場合は、コードを適宜更新してください。
| バージョン 5 コード | バージョン 7 コード.サブコード |
|---|---|
| RequestParameterMissing | InvalidRequest.ParameterMissing |
| RequestParameterInvalidValue | InvalidRequest.ParameterInvalidValue |
| ResourceAccessDenied | InsufficientAuthorization |
| ExceededVolume | RateLimitExceeded |
| ExceededQpsLimit | RateLimitExceeded |
| 無効 | InsufficientAuthorization.AuthorizationDisabled |
| UnexpectedError | ServerError.UnexpectedError |
| DataSourceErrors | ServerError.ResourceError |
| AuthorizationMissing | InvalidAuthorization.AuthorizationMissing |
| HttpNotAllowed | InvalidRequest.HttpNotAllowed |
| UserAgentMissing | InvalidRequest.ParameterMissing |
| NotImplemented | ServerError.NotImplemented |
| InvalidAuthorization | InvalidAuthorization |
| InvalidAuthorizationMethod | InvalidAuthorization |
| MultipleAuthorizationMethod | InvalidAuthorization.AuthorizationRedundancy |
| ExpiredAuthorizationToken | InsufficientAuthorization.AuthorizationExpired |
| InsufficientScope | InsufficientAuthorization |
| Blocked | InvalidRequest.Blocked |
クエリ パラメーター
modulesRequestedクエリ パラメーターの名前が modules に変更されました。Annotations の名前が Tags に変更されました。 Tags に対する modules クエリ パラメーターについての説明を参照してください。
ShoppingSources フィルター値をサポートしている市場の一覧が、en-US のみに変更されました。 imageType に関する説明を参照してください。
イメージの分析情報の変更
ImagesInsights の
annotationsフィールドの名前がimageTagsに変更されました。AnnotationModuleオブジェクトの名前が ImageTagsModule に変更されました。Annotationオブジェクトの名前が Tag に変更され、confidenceフィールドが削除されました。Image オブジェクトの
insightsSourcesSummaryフィールドの名前がinsightsMetadataに変更されました。InsightsSourcesSummaryオブジェクトの名前が InsightsMetadata に変更されました。https://api.cognitive.microsoft.com/bing/v7.0/images/detailsエンドポイントが追加されました。 イメージの分析情報を要求するときは、/images/search エンドポイントの代わりにこのエンドポイントを使用します。 Image Insights に関する説明を参照してください。次のクエリ文字列パラメーターは、
/images/detailsエンドポイントでのみ有効となりました。ImageInsightsResponseオブジェクトの名前が ImageInsights に変更されました。ImageInsights オブジェクト内の次のフィールドのデータ型が変更されました。
relatedCollectionsフィールドの型がImageGallery[]から RelatedCollectionsModule に変更されました。pagesIncludingフィールドの型がImage[]から ImagesModule に変更されました。relatedSearchesフィールドの型がQuery[]から RelatedSearchesModule に変更されました。recipesフィールドの型がRecipe[]から RecipesModule に変更されました。visuallySimilarImagesフィールドの型がImage[]から ImagesModule に変更されました。visuallySimilarProductsフィールドの型がProductSummaryImage[]から ImagesModule に変更されました。ProductSummaryImageオブジェクトが削除され、製品関連のフィールドが Image オブジェクトに移動されました。Imageオブジェクトに製品関連のフィールドが含まれるのは、イメージ分析情報の応答で、イメージが、視覚的に類似した製品の一部として含まれている場合のみです。recognizedEntityGroupsフィールドの型がRecognizedEntityGroup[]から RecognizedEntitiesModule に変更されました。
ImageInsights の
categoryClassificationフィールドの名前がannotationsに変更され、型がAnnotationsModuleに変更されました。
イメージの応答
Images から displayShoppingSourcesBadges フィールドと displayRecipeSourcesBadges フィールドが削除されました。
Images の
nextOffsetAddCountフィールドの名前がnextOffsetに変更されました。 オフセットの使用方法も変更されています。 以前は、offset クエリ パラメーターをnextOffsetAddCountの値、前の offset の値、および結果内のイメージ数の合計に設定していましたが、offsetをnextOffsetの値に設定するようになりました。
非破壊的変更
クエリ パラメーター
imageType フィルターに使用可能な値として、Transparent が追加されました。 Transparent フィルターは、透明な背景を持つイメージのみを返します。
license フィルターに使用可能な値として、Any が追加されました。 Any フィルターは、ライセンスを受けているイメージのみを返します。
maxFileSize および minFileSize クエリ パラメーターが追加されました。 これらのフィルターを使用すると、ファイル サイズが範囲内であるイメージが返されます。
maxHeight、minHeight、maxWidth、minWidth の各クエリ パラメーターが追加されました。 これらのフィルターを使用すると、高さと幅が範囲内であるイメージが返されます。
オブジェクトの変更
Offer オブジェクトに
descriptionフィールドとlastUpdatedフィールドが追加されました。ImageGallery オブジェクトに
nameフィールドが追加されました。Images オブジェクトに
similarTermsフィールドが追加されました。 このフィールドには、ユーザーのクエリ文字列と意味的に類似している用語のリストが含まれます。