読者です 読者をやめる 読者になる 読者になる

adish intelligence

アディッシュ株式会社のエンジニアブログです。

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に参加しています。

記事の背景

f:id:shirakiya:20161202103905p:plain

タイトルからお分かりになる通り、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 v5Microsoft 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上のマイページに行くことができます。

f:id:shirakiya:20161202095415p:plain

ここから画面右にある「verification」からアカウントの確認を行います。押すとメールが送られてきて、その中に添付されているURLを押すと確認完了になる、よくあるやつです。
それを終えると、次に「Request new trials」というボタンが画面右下にあるので、これをクリックすると無料で利用可能なAPIの一覧が、無料枠の説明と共に表示されます。

f:id:shirakiya:20161202095436p:plain

その中にある「Bing Search」と利用規約同意にチェックを付けると、サブスクリプションキーが発行されます。

f:id:shirakiya:20161202095457p:plain

f:id:shirakiya:20161202095513p:plain

ちなみに、この画像のようにサブスクリプションキーが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を始める、という感じでしたが、無事年を越すことができそうです。

*1:ALICEチームとは機械学習に関する開発を行っているチームです。アディッシュの技術開発部のチーム構成については以前投稿した記事をご覧頂ければと思います。