Bing Search API v2 から v5 へ移行した話
この記事は Gaiax Advent Calendar 2016 の3日目の記事です。
こんにちは、アディッシュ株式会社(以下、adish)・ALICEチーム*1の白木です。
（何も考えずに今年も12/3が空いていたのでこの日に参加予定を入れたら去年のGaiax Advent Calendarでも12/3だったので、深層心理で12/3が好きなのかも。）
Gaiax Advent Calendarでいきなりadishなる会社名を名乗りましたが、adishはGaiaxのグループ会社で、去年と同じく今年もGaiax Advent Calendarに参加しています。
記事の背景
タイトルからお分かりになる通り、Gaiax Advent CalendarでBing Search APIについての記事を投稿しようとしているわけですが、これはadishで利用している外部APIの1つなので、題材としました。
利用している理由は、このブログで以前投稿した「PythonでBing Search APIを使って画像データを集める方法」という記事の中で説明をしているのですが、adishでは今年めっきりバズワードになった ディープラーニング を用いた機械学習技術を画像認識タスクに利用しており、その際の検証目的で使う画像の取得にBing Search APIを用いています。
上の記事で紹介しているのは、Bing Search API v2についてで、これはMicrosoft DataMarketから利用登録を行うものでした。
しかし、2016年7月1日から新しいバージョンのBing Search API v5がMicrosoft Cognitive Services上でリリースされ、同時に旧バージョンのBing Search API v2が使えなくなる、というアナウンスがなされました。
そしてその旧バージョンの利用期限が 2016年12月15日 までとなっています。
・・・
期限ギリギリッ!!!!!!!!
はい、そういうわけで今回は、v2からv5へ移行すべくして移行したその作業手順と、画像取得を主とした新しいAPIの使い方について紹介します。
Bing Search API v5を使うまで
ありがたいことに、Microsoftからv2からv5に移行する人向けに専用の記事を用意してくれていますので、それを参考に進めてみます。
https://msdn.microsoft.com/en-US/library/mt707570.aspx
あと前提として、Microsoftアカウントを持っていることとします。もし持っていない場合はこちらから新規登録してください。
※ Bing Search API v5（無料版）の利用はMicrosoft Cognitive Services上で行うものであり、Microsoft Cognitive Servicesに登録できていれば利用可能です。Microsoftアカウントの他に、GithubアカウントやLinkedinアカウントがあればサインアップが行えるようですが、今回はMicrosoftアカウントを使った方法を説明します。
Microsoft Cognitive Servicesからサブスクリプションキーを取得する
まず、サブスクリプションキーを取得します。これはAPIキーのようなもので、Microsoft Cognitive Servicesのアカウントを持っていれば取得可能です。
まず、Microsoft Cognitive Servicesのサインアップページからサインアップし、アプリ連携するとCognitive Services上のマイページに行くことができます。
ここから画面右にある「verification」からアカウントの確認を行います。押すとメールが送られてきて、その中に添付されているURLを押すと確認完了になる、よくあるやつです。
それを終えると、次に「Request new trials」というボタンが画面右下にあるので、これをクリックすると無料で利用可能なAPIの一覧が、無料枠の説明と共に表示されます。
その中にある「Bing Search」と利用規約同意にチェックを付けると、サブスクリプションキーが発行されます。
ちなみに、この画像のようにサブスクリプションキーが2つ発行されますが、これは
Each service returns a primary and secondary key. Both keys are tied to the same quota, so you may use either key.
https://msdn.microsoft.com/en-us/library/mt712546.aspx#Anchor_0 より
とのことで、どちらを使っても良いようです。
Bing Search API v5の種類
Bing Search API v5は、
- Web Search API（Webページ+画像+動画+ニュース）
- News Search API（ニュース検索）
- Image Search API（画像検索）
- Video Search API（動画検索）
の4つに分かれており、{News|Image|Video} Searchはそれぞれニュース、画像、動画のみ取得することができますが、Web Searchはその全ての情報を取得することができます。
ただ、ニュース・画像・動画等全て入っていることは担保されているわけではなく、検索クエリによってはWebページだけの場合が合ったりするので、基本は欲しい情報に適したAPIを使う必要がありそうです。
今回は画像検索の結果を得たいので、Image Search APIを使うことにします。
Image Search APIを使う
次に実際にAPIを使ってみることにします。
APIのドキュメントは、
- 使い方
- リファレンス
にまとめられているので、詳しくはこちらをご参照ください。
Request Header
Bing Search APIを使うには、Request Headerに Ocp-Apim-Subscription-Key={取得したサブスクリプションキー}を加えてることで正常なResponseが得られます。
（User-Agent,X-MSEdge-ClientID,X-Search-ClientIPも積極的に設定してね、とも書いてあるのですが、これを設定した時の影響は調査していません、ごめんなさい。）
Endpoint
Endpointは以下の通り。
https://api.cognitive.microsoft.com/bing/v5.0/images/search
クエリパラメータ
クエリパラメータで必須なのは、qのみで、こちらに検索したい文字列を指定します。
オプションのパラメータは、
- 検索の条件に関するパラメータ
- 結果画像に対する条件に関するパラメータ
を参考に指定してください。
例えばよく使うのは、
count: 1度の検索で何件取得するか（デフォルト: 35件、最大: 150件）offset: 検索トップからどれだけスキップした後の画像を取得するかmkt: どの地域での検索結果を得るか（日本であればja-JPを指定する。
などでしょうか。ちなみに count は、v2だと $top というパラメータ名であったりと、こうしたパラメータ名の変更や利用できるパラメータの変更が多くあるのでパラメータに関しては特に要チェックです。
レスポンス
実際にリクエストしてみます。
今回は、日本での検索で "リンゴ" という検索文字列を指定し、結果2件だけ受け取る、というリクエストを行いました。
- Request URL
https://api.cognitive.microsoft.com/bing/v5.0/images/search?q=%e3%83%aa%e3%83%b3%e3%82%b4&mkt=ja-JP&count=2
- Response
{ "_type": "Images", "instrumentation": { "pageLoadPingUrl": "https://www.bingapis.com/api/ping/pageload?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&Type=Event.CPT&DATA=0" }, "webSearchUrl": "https://www.bing.com/cr?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&rd=1&h=P17B0qhd32lnjN5_RH7oKgCuhapuQtRSZ6r-fx_BC3U&v=1&r=https%3a%2f%2fwww.bing.com%2fimages%2fsearch%3fq%3d%25E3%2583%25AA%25E3%2583%25B3%25E3%2582%25B4%26FORM%3dOIIARP&p=DevEx,5028.1", "totalEstimatedMatches": 948, "value": [ { "name": "Illustratorで林檎を描いてみた ...", "webSearchUrl": "https://www.bing.com/cr?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&rd=1&h=XC5oD8iG4FFpgigR6S8K5sYJGxtYq1tMKugZUr4_6Js&v=1&r=https%3a%2f%2fwww.bing.com%2fimages%2fsearch%3fview%3ddetailv2%26FORM%3dOIIRPO%26q%3d%25e3%2583%25aa%25e3%2583%25b3%25e3%2582%25b4%26id%3d89C28207FC57BC63DDAFED0425CC32B3901B10FF%26simid%3d608001155137668054&p=DevEx,5006.1", "thumbnailUrl": "https://tse3.mm.bing.net/th?id=OIP.M992c7d29fcff00d731f580975bee5352o0&pid=Api", "datePublished": "2014-08-01T23:44:00", "contentUrl": "http://www.bing.com/cr?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&rd=1&h=ncKfI_uF6wfrn08gg4KKgbx-LqVWyO1LWh6APvnGNoc&v=1&r=http%3a%2f%2fcdn-ak.f.st-hatena.com%2fimages%2ffotolife%2ff%2fforeverLab%2f20140327%2f20140327203348.jpg&p=DevEx,5008.1", "hostPageUrl": "http://www.bing.com/cr?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&rd=1&h=dpKYzf4HQGiCt8ahRdWfqt5-tlua-3hgX96PGlBpV90&v=1&r=http%3a%2f%2fforeverlab.hatenablog.com%2fentry%2f2014%2f03%2f27%2f205248&p=DevEx,5007.1", "contentSize": "50081 B", "encodingFormat": "jpeg", "hostPageDisplayUrl": "foreverlab.hatenablog.com/entry/2014/03/27/205248", "width": 640, "height": 427, "thumbnail": { "width": 300, "height": 200 }, "imageInsightsToken": "ccid_mSx9Kfz/*mid_89C28207FC57BC63DDAFED0425CC32B3901B10FF*simid_608001155137668054", "imageId": "89C28207FC57BC63DDAFED0425CC32B3901B10FF", "accentColor": "C84403" }, { "name": "奇跡のリンゴ』上映中！中村 ...", "webSearchUrl": "https://www.bing.com/cr?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&rd=1&h=xMJhqVdP-6nMW2NYP88Y_WuWz138HJsNH-SAlb3sjLk&v=1&r=https%3a%2f%2fwww.bing.com%2fimages%2fsearch%3fview%3ddetailv2%26FORM%3dOIIRPO%26q%3d%25e3%2583%25aa%25e3%2583%25b3%25e3%2582%25b4%26id%3dBC8E6F42DC222DC074E1952452F1332F200CCFE8%26simid%3d608026022994903221&p=DevEx,5012.1", "thumbnailUrl": "https://tse2.mm.bing.net/th?id=OIP.M52d8fb557aa4e3fa34feeb0af6beaa6eo0&pid=Api", "datePublished": "2016-03-19T15:30:00", "contentUrl": "http://www.bing.com/cr?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&rd=1&h=3aTuMYOrZfWvXFmmaTs_HIeoppH5-wEUxgD1cweybhk&v=1&r=http%3a%2f%2fwww.arakawaoki.co.jp%2fnews%2fwp-content%2fuploads%2f2013%2f06%2f8facebad793516c2228e862ca9b783d6.jpg&p=DevEx,5014.1", "hostPageUrl": "https://www.bing.com/cr?IG=89CB4863E5DC43F9804095E7823C1036&CID=27CB8EF3C20E62CC2C89872DC31C6375&rd=1&h=4gsI4XakrhOoP7ZS2xGE06wnzCahftXnzIdAvK6HNdU&v=1&r=https%3a%2f%2fwww.arakawaoki.co.jp%2fnews%2f%3fp%3d2525&p=DevEx,5013.1", "contentSize": "41278 B", "encodingFormat": "jpeg", "hostPageDisplayUrl": "https://www.arakawaoki.co.jp/news/?p=2525", "width": 560, "height": 372, "thumbnail": { "width": 300, "height": 199 }, "imageInsightsToken": "ccid_Utj7VXqk*mid_BC8E6F42DC222DC074E1952452F1332F200CCFE8*simid_608026022994903221", "imageId": "BC8E6F42DC222DC074E1952452F1332F200CCFE8", "accentColor": "3F0E04" } ], "nextOffsetAddCount": 0, "displayShoppingSourcesBadges": false, "displayRecipeSourcesBadges": true }
画像情報はvalueの中に配列で入っています。
当然ですがオプション指定によって、かなり検索結果が変わるので、便利ですね。
Pythonでリクエストする
一応PythonでAPIをcallしてレスポンスを受け取る超簡単なコードを記しておきます。
（requestsは外部モジュールではありますが、非常に使い勝手が良いのでこちらを用いています。）
# -*- coding: utf-8 -*- import requests query = 'りんご' endpoint = 'https://api.cognitive.microsoft.com/bing/v5.0/images/search' headers = { 'Ocp-Apim-Subscription-Key': <SUBSCRIPTION_KEY> } params = { 'q': query, 'mkt': 'ja-JP', 'count': 2, 'offset': 0, } response = requests.get(endpoint, headers=headers, params=params) print(response) #=> 上記のJSONのレスポンスが得られる
以下のMicrosoftのページに行けば各言語の簡単な使い方を記してくれていますので、こちらを参考にしてみるのも良いと思います。
https://dev.cognitive.microsoft.com/docs/services/56b43f0ccf5ff8098cef3808/operations/571fab09dbe2d933e891028f
さいごに
以上にBing Search API v5の紹介を行いました。
旧バージョンについては、
https://datamarket.azure.com/dataset/bing/search
からAPIの利用を停止するか、もしくは2016年12月15日になれば使えなくなるはずなので放っておいても良いでしょう。これにて移行…というか完全に新しくv5を始める、という感じでしたが、無事年を越すことができそうです。
