Cloud Vision APIの使い方まとめ (サンプルコード付き)

Cloud Vision APIを利用するには認証が必須です。認証の種類は様々ですが、この記事では一番手軽なAPIキーによる認証を説明します。ということで、認証に必要となるAPIキーをまずは取得しましょう。

課金設定について

Cloud Vision APIを利用するには、請求が発生する、しないに関わらず、クレジットカード(またはデビッドカード)を登録し、課金を有効な状態にしなければいけません。そして、Google Developers Consoleにおいては、課金を無効にすることはできても、登録したカードの情報を削除することができない仕様になっています。これらを踏まえて、自己責任でご利用下さい。「この記事の通りに設定したけど料金が発生したぞ」などという苦情は一切受け付けないことを、あらかじめ、ご了承下さい。

Googleのアカウントを用意する

APIキーを取得するためには、Googleのユーザーアカウントが必要です。まだ持っていない人は作成して下さいね。

Google Developers Consoleにアクセスする

アカウントが用意できたら、開発者たちの管理画面であるGoogle Developers Consoleにアクセスして下さい。

プロジェクトを作成する

ページにアクセスしたら、まずは右上にある「プロジェクトを選択して下さい」という部分をクリックして下さい。

メニューが出てきます。「プロジェクトの作成」をクリックして下さい。「プロジェクト」とは、これから作成するアプリケーション(PHPなど)をまとめるためのカテゴリのようなものだと思って下さい。

新しいプロジェクトを作成するためのフォームが出てきます。ここで、好きなプロジェクト名を入力して「作成」のボタンをクリックして下さい。ボタンをクリックして問題がなければ、プロジェクトが作成されます。

「作成」をクリックしてから少し待てば、このように新しいプロジェクトが作成されます。このプロジェクトに紐付いた、APIキーをこれから作成するということを意識しておきましょう。

Cloud Vision APIを有効にする

作成したプロジェクトにおいて、目的の「Cloud Vision API」を利用できるように、有効化する作業を行ないます。まずは、左上にあるメニューボタンをクリックして下さい。

メニューが表示されます。その中から「API Manager」をクリックして下さい。

Googleが提供するAPIの一覧画面に移動します。探すのが大変なので、検索フォームでキーワード検索をしましょう。

「Cloud Vision API」と入力すれば、キーワードにマッチして、目的に「Cloud Vision API」が表示されると思います。このタイトルをクリックして下さい。

「Cloud Vision API」の専用画面に移動します。タイトルの横に、有効、無効を切り替えるためのボタンがあります。最初は有効ではないので、「Enable(有効に切り替える)」というボタンが表示されていますね。これをクリックして下さい。

APIを有効化することができたはずです。プロジェクトを作成したばかりの場合、まだ認証方法を1つも設定していない状態のため、このように「認証情報を設定して下さい」というアラートが表示されると思います。これが出た人は、とりあえず作業としてサービスアカウントを作成してしまいましょう。「認証情報に進む」のボタンをクリックして下さい。このアラートが出ない人は、そのまま次項の「APIキーを作成する」に進んで下さいね。

「プロジェクトへの認証情報の追加」という画面が表示されます。「使用するAPI」には「Cloud Vision API」を選択し、「Google App Engine」を使用しますか？という項目は「いいえ」を選択して、「必要な認証情報」のボタンをクリックして下さい。

新たにフォームが表示されます。「サービスアカウントの名前」と「キーのタイプ」を選択して、「次へ」をクリックして下さい。サービスアカウントとは、「APIを利用するためのアカウント」で、「キー」とは、そのアカウントで認証をするための情報が含まれたファイルです。この記事では、APIキーによる認証で説明するため、サービスアカウントは利用しません。ただ、やれと言われているから登録しているだけです。「キー」はここでは使わないので、「JSON」と「P12」、どちらを選択しても問題ありません。「アカウントの名前」に関しても、後でどうにでもできるので適当な名前で大丈夫です。繰り返しますが、この記事では使いません。

問題がなければ、サービスアカウントが作成されます。また、同時に「キー」のファイルが自動でダウンロードされます。このファイルは認証に利用する重要なものなので、今は管理しないならしないで、キッチリと削除をしてしまって下さい。後で再発行できます。それでは、サービスアカウントのことは忘れて、APIキーを取得しましょう。…念のため、断っておきますが、簡易なAPIキーによる認証よりも、サービスアカウントによる認証の方が推奨されます。ただ、ここでは説明を簡易にしたい都合でAPIキーを利用するということです。

APIキーを作成する

続いて、認証に利用するためのAPIキーを作成しましょう。画面左上にあるメニューボタンをクリックして下さい。

メニューが表示されます。その中から「API Manager」をクリックして下さい。

「API Manager」の画面に移動します。左側にあるメニューの中から「認証情報」をクリックして下さい。

「認証情報」の画面に移動します。上部にある「Create credentials」をクリックして下さい。

すると、作成できる認証キーの種類一覧が表示されます。この中から「APIキー」をクリックして下さい。

APIキーの種類を選択するフォームが表示されます。この記事では、ブラウザでPHPを使ってAPIを利用するので、「ブラウザキー」を選択します。

APIキーの名前と、許可するリファラーを設定します。キーの名前は、他のキーと区別するためのものです。APIキーをたくさん作った後に「このAPIキーはどのプログラムで使ってたっけ？」とならないように、分かりやすい名前を付けて下さい。この見本のようにサイト名にしてもいいですが、Cloud Vision APIしか使わないなら、「SYNCER (Cloud Vision API)」と付けた方が後で分かりやすいでしょうね。

もう1つは許可するリファラーの設定です。例えば、APIキーを他人に知られてしまったとしても、許可するリファラーをhttps://syncer.jpだけにしておけば、APIキーを手に入れた他人がhttps://syncer.jp以外のサイトで利用できなくなるので安全です。https://syncer.jp/*としておけば、https://syncer.jp上の全てのページから利用することができます。

なお、PHPのcURLやfile_get_contents()でリクエストする時、そのままだとリファラーが付きません。そのため、ヘッダーで指定してあげる必要があります。ちゃぶ台を返すようで大変申し訳ないのですが、これはイコール、他人がいくらでも偽装可能ということになってしまいますよね。なので、許可するリファラーを設定したとしても気休め程度にしかならない。APIキーは絶対に他人に知られてはいけない、という点を意識しておきましょう。

問題がなければ、「作成」をクリックするとこのようにAPIキーが発行されます。このキーを利用しますので、控えておいて下さい。他人に知られてはいけません。

「認証情報」の画面に戻ります。作成したAPIキーの情報を確認できますね。ビックリマークが付いているのは、リファラーを設定していないためです。「他人のサイトで勝手にAPIキーを使われるかもしれませんよ〜」ということですね。理論上、APIキーがバレなければ問題ありませんが、絶対ということはないので、必ず、本稼働時にはリファラーを制限して下さい。APIキーのタイトルをクリックすると、リファラーを再設定できます。

課金を有効にする

Cloud Vision APIは、課金を有効にしないと利用できません。APIキーは発行できたので、そのまま使ってみるか、といった具合にリクエストをしても、次のエラーメッセージが含まれたJSONが返ってきます。「課金有効にしろや」というメッセージですね。

Project syncer-1228 (#314246477086) has billing disabled. Please enable it.

Google Developersにクレジットカードを登録すると、登録を削除することができません。課金を無効にしても、クレジットカードの情報は登録したままにしないといけないということです。このことをよく思わない場合は、APIの利用を諦めて下さい。迷う場合は登録しないのが一番良い選択肢です。この記事内でデモを稼働させているので、登録する前に色々と試してみて下さいね。

それではお支払い設定、課金設定をしていきましょう。画面左上にあるメニューボタンをクリックして下さい。

メニューの中から「お支払い」をクリックして下さい。

請求先となるアカウントを登録します。「請求先アカウントの作成」をクリックして下さい。

請求先となるクレジットカード、住所の情報を入力する画面が表示されます。必要な情報を入力し、「登録」をクリックして下さい。初めての場合は「無料試用を開始」となっていますが、ここでは無料試用がどのような仕組みかは解説しません。

請求先アカウントが登録されました。このように案内メッセージが表示されるので、よろしければ「OK」をクリックして下さい。これで、Cloud Vision APIを利用する準備が完了しました！お疲れ様でした。

お金が発生することに関しては面倒でも自分でドキュメントを確認するべきですが、一応説明しておきます。課金状態を無効にしたい場合は、画面右上にある「請求先アカウントを閉鎖」をクリックして下さい。これはユーザーアカウントの削除ではないのでご安心下さい。

課金額が一定数を超えた時に通知メールを受け取ることができる、アラート設定をしておきましょう。画面左側にある「アラート」の項目から設定できます。なお、メールは請求先アカウントを登録する時に入力したメールアドレスに届きます。登録時に確認用のメールが届いているはずなので、本文にあるリンクをクリックしてメール認証を終えておきましょう。そうしないと通知が届きません。

APIキーを取得したら、まずは細かい仕様は意識せずに、リクエストを送って結果を取得してみましょう。下記に最も簡易なサンプルコードを用意したのでぜひ試してみて下さいね。リクエストが通らない場合、APIキー、もしくは画像へのパスを再度確認して下さい。

<?php
	// APIキー
	$api_key = "" ;

	// リファラー (許可するリファラーを設定した場合)
	$referer = "https://...com/" ;

	// 画像へのパス
	$image_path = "./image.jpg" ;

	// リクエスト用のJSONを作成
	$json = json_encode( array(
		"requests" => array(
			array(
				"image" => array(
					"content" => base64_encode( file_get_contents( $image_path ) ) ,
				) ,
				"features" => array(
					array(
						"type" => "FACE_DETECTION" ,
						"maxResults" => 3 ,
					) ,
					array(
						"type" => "LANDMARK_DETECTION" ,
						"maxResults" => 3 ,
					) ,
					array(
						"type" => "LOGO_DETECTION" ,
						"maxResults" => 3 ,
					) ,
					array(
						"type" => "LABEL_DETECTION" ,
						"maxResults" => 3 ,
					) ,
					array(
						"type" => "TEXT_DETECTION" ,
						"maxResults" => 3 ,
					) ,
					array(
						"type" => "SAFE_SEARCH_DETECTION" ,
						"maxResults" => 3 ,
					) ,
					array(
						"type" => "IMAGE_PROPERTIES" ,
						"maxResults" => 3 ,
					) ,
				) ,
			) ,
		) ,
	) ) ;

	// リクエストを実行
	$curl = curl_init() ;
	curl_setopt( $curl, CURLOPT_URL, "https://vision.googleapis.com/v1/images:annotate?key=" . $api_key ) ;
	curl_setopt( $curl, CURLOPT_HEADER, true ) ; 
	curl_setopt( $curl, CURLOPT_CUSTOMREQUEST, "POST" ) ;
	curl_setopt( $curl, CURLOPT_HTTPHEADER, array( "Content-Type: application/json" ) ) ;
	curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false ) ;
	curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true ) ;
	if( isset($referer) && !empty($referer) ) curl_setopt( $curl, CURLOPT_REFERER, $referer ) ;
	curl_setopt( $curl, CURLOPT_TIMEOUT, 15 ) ;
	curl_setopt( $curl, CURLOPT_POSTFIELDS, $json ) ;
	$res1 = curl_exec( $curl ) ;
	$res2 = curl_getinfo( $curl ) ;
	curl_close( $curl ) ;

	// 取得したデータ
	$json = substr( $res1, $res2["header_size"] ) ;				// 取得したJSON
	$header = substr( $res1, 0, $res2["header_size"] ) ;		// レスポンスヘッダー

	// 出力
	echo "<h2>JSON</h2>" ;
	echo $json ;

	echo "<h2>ヘッダー</h2>" ;
	echo $header ;

実際にCloud Vision APIを利用して、画像認識をするデモです。試したい画像を選んでクリックしてみて下さいね。なお、レスポンスが速いのは結果を24時間キャッシュしているためです。

具体的なリクエスト方法を説明していきます。基本的な3点を押さえれば、あとは自分好みに調整してリクエストするだけです。

エンドポイント

2016年2月現在、エンドポイントは1つだけです。このURLのkeyパラメータに、取得したAPIキーを付けましょう。

画像の指定

画像認識の対象となる、画像ファイルの指定は、基本的にbase64エンコードしたものを用います。例えばPHPの場合は、base64_encode()を使って次のように画像をエンコードできます。

<?php
// 画像のパス
$image_path = "./image.jpg" ;

// 画像を取得
$image_raw = file_get_contents( $image_path ) ;

// 画像をbase64エンコード
$image_base64_encoded = base64_encode( $image_raw ) ;

JSONでリクエストする

一般的なAPIリクエストは、次のようにエンドポイントにGETメソッドでパラメータを付けてリクエストを送ることで、情報を取得します。

しかし、このCloud Vision APIの場合は、JSONでリクエスト送ります。例えば、textはhogeでdateは20160703だ、という時は、次のようなJSONを作成してリクエストするということです。

{
	"text": "hoge" ,
	"date": "20160703"
}

ヘッダーでJSONを明示する

さて、JSONを相手のサーバーに送る場合のルールは1つです。ヘッダーで「送るデータの形式はJSONだぞ、コラ」ということを明示してあげましょう。データがJSONであることを明示するためのヘッダーは次の通りです。

Content-Type: application/json

リクエストを送る時に、このヘッダーを加えるには、PHPのcURLでは次の通り、カスタムヘッダーとして指定します。相手サーバーはこのヘッダーを確認することで、「送られたデータの形式がJSONなんだな、コラ」ということを確認できます。

curl_setopt( $curl, CURLOPT_HTTPHEADER, array( "Content-Type: application/json" ) ) ;

ボディにJSONを指定する

肝心のJSONはボディに含めます。JSONを送り付けるのでメソッドは当然、POSTということになります。

curl_setopt( $curl, CURLOPT_CUSTOMREQUEST, "POST" ) ;
curl_setopt( $curl, CURLOPT_POSTFIELDS, $json ) ;

cURLによるリクエスト例

cURLでは次のように、オプションを指定します。こうして見ると記述が多くて嫌になりそうですが、調整すればいいのは$api_keyと$jsonと$referer(許可するリファラーを設定している場合)の部分だけです。

// cURLの開始
$curl = curl_init() ;

// オプション
curl_setopt( $curl, CURLOPT_URL, "https://vision.googleapis.com/v1/images:annotate?key=" . $api_key ) ;	// リクエストURL (APIキーを付ける)
curl_setopt( $curl, CURLOPT_HEADER, true ) ; 	// レスポンスヘッダーを取得する
curl_setopt( $curl, CURLOPT_CUSTOMREQUEST, "POST" ) ;	// POSTメソッドでリクエストする
curl_setopt( $curl, CURLOPT_HTTPHEADER, array( "Content-Type: application/json" ) ) ;	// ヘッダーにJSONを明示する
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false ) ;	// 証明書の検証を行わない
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true ) ;	// 取得した内容をそのまま出力せずに文字列で返す (変数に入れられる)
curl_setopt( $curl, CURLOPT_TIMEOUT, 15 ) ;		// タイムアウトの秒数
curl_setopt( $curl, CURLOPT_REFERER, $referer ) ;		// リファラー(許可するリファラーを設定している場合)
curl_setopt( $curl, CURLOPT_POSTFIELDS, $json ) ;	// JSONの内容

// データの取得
$res1 = curl_exec( $curl ) ;		// ボディの内容 (ボディとヘッダーが混ざっている)
$res2 = curl_getinfo( $curl ) ;		// ヘッダーの情報 (ヘッダーのサイズを取得して、ボディからヘッダーを引き剥がす)

// cURLの終了
curl_close( $curl ) ;

// 取得したデータ
$json = substr( $res1, $res2["header_size"] ) ;		// 取得したJSON (ボディからヘッダーを引き剥がした)
$header = substr( $res1, 0, $res2["header_size"] ) ;	// レスポンスヘッダー (ボディから引き剥がした分)

それでは、リクエストを送るためのJSONを作成してみましょう。PHPでは、json_encode()を利用することで、配列をJSONに変換できます。「サンプルコード」の章にあるJSONを例に取ると次の通りです。次のように、配列をjson_encode()の引数に指定していますね。

// リクエスト用のJSONを作成
	$json = json_encode( array(
		"requests" => array(
			array(
				"image" => array(
					"content" => base64_encode( file_get_contents( $image_path ) ) ,
				) ,
				"features" => array(
					array(
						"type" => "LABEL_DETECTION" ,
						"maxResults" => 1 ,
					) ,
				) ,
			) ,
		) ,
	) ) ;

$jsonの中身は、次のようなJSON(正確には文字列)になっているんです。これを、リクエストする際のJSONとして、cURLのCURLOPT_POSTFIELDSオプションに指定すればいいということですね。JSONを手入力で書くのは、現実的にはとても大変なので、配列を作成し、それをjson_encode()でJSONに変換する手順を取るのが一番簡単です。

{
    "requests": [
        {
            "image": {
                "content": "base64エンコードした画像"
            },
            "features": [
                {
                    "type": "LABEL_DETECTION",
                    "maxResults": 1
                }
            ]
        }
    ]
}

リクエスト用のJSONの材料となる、個々のオブジェクトをまとめてみました。これらを参考に、リクエスト用のJSONを構築してみて下さいね。

requests

リクエストで送るJSONは、requestsプロパティに指定した配列に、リクエストの数だけ、後述のAnnotateImageRequestというオブジェクトを含める形になります。

{
    "requests": []
}

例えば3つの画像を認識してもらいたい場合は、AnnotateImageRequestオブジェクトを3つ配列に含めて下さい。次のような構造になります。

AnnotateImageRequest

AnnotateImageRequestオブジェクトは、画像認識の対象となる画像の情報を含むオブジェクトです。image、AnnotateImageRequest、features、3つのオブジェクトで成り立っています。imageContextは省略してかまいません。このAnnotateImageRequestオブジェクトを、requestsの配列の中に、必要な数だけ含めます。

Image

Imageオブジェクトは、画像のデータを示すオブジェクトです。ここで指定した画像が、Cloud Vision APIで解析されます。content、sourceの2種類のプロパティがあり、どちらかの指定が必須です。base64エンコードした画像データを指定する場合はcontentを。そうではなく、Google Cloud Storageに設置してある画像のURIで指定する場合はsourceを指定して下さい。contentとsourceの両方を指定した場合、sourceが無視されます。

ImageSource

ImageSourceオブジェクトは、解析対象となる画像のデータをGoogle Cloud Storageに設置してある画像のURIで指定する場合に用いるオブジェクトです。gcsImageUriプロパティに、gs://から始まるURIを指定して下さい。

Feature

Featureオブジェクトは、解析に利用するツールの種類を指定するためのオブジェクトです。例えば、画像認識と単に言っても、OCR(画像の中の文字認識)をしたいのか。顔解析をしたいのか。または場所解析をしたいのか。目的は様々ですよね。このオブジェクトで「どのツールを使った画像認識をしてほしい」ということを指定するわけです。FeatureはtypeとmaxResultsで1セットのオブジェクトです。配列で複数のFeatureオブジェクトを指定できます。

Type

Featureオブジェクトのtypeプロパティに指定できる、ツールの種類を示す文字列の一覧です。

ImageContext

ImageContextは、画像解析をするGoogleのサーバーに対して、解析のヒントとなる追加情報を与えるためのオブジェクトです。文字解析の際に言語を指定したり、ランドマーク検出などの際に位置情報を範囲で指定できます。

LatLongRect

LatLongRectは、位置情報の範囲を指定するためのオブジェクトです。minLatLngプロパティに南西の、maxLatLngプロパティに北東の位置座標を指定することで、その2点を対角線とした長方形の範囲を表現します。

LatLong

LatLongは、minLatLngとmaxLatLng、2つのプロパティに指定できるオブジェクトです。

リクエストに成功すると、画像認識の結果をJSONで取得することができます。この章では、JSONの各プロパティにどんな意味があるのかをまとめました。

Response

取得できるJSONの内容は、全て、このResponseオブジェクトに、結果の数だけ、AnnotateImageResponseオブジェクトが含まれています。

AnnotateImageResponse

AnnotateImageResponseは、画像認識の結果を含むオブジェクトです。Featureで指定した画像認識のツールの分だけ、情報が含まれています。例えば、顔検出を利用すれば、faceAnnotationsが含まれ、ランドマーク検出を利用すれば、labelAnnotationsが含まれます。リクエストに失敗した場合は、エラーの内容がerrorオブジェクトに含まれます。

FaceAnnotation

FaceAnnotationは、顔検出の結果となる情報を含むオブジェクトです。顔の各パーツの位置など、様々な情報が含まれています。

BoundingPoly

BoundingPolyは、範囲の情報を含むオブジェクトです。範囲は4つの点を結んだポリゴン(四角形)で表現されます。顔検出における顔の範囲、文字検出における文字の範囲、ロゴ検出におけるロゴの範囲など、様々なデータに含まれます。範囲の情報はverticesオブジェクトに含まれています。

Vertex

Vertexは、範囲を示すポリゴンの、4つの頂点の位置の情報を含むオブジェクトです。位置は画像の左上を基準としたX座標(右に何px離れているか)、Y座標(下に何px離れているか)で表現されます。距離は、リクエストで指定した画像のオリジナルの大きさに準じたものとなっています。画像を縮小して表示する際は、スケール(縮小率)を考慮しなければいけません。

Landmark

Landmarkは、パーツ(type)と位置(position)を1セットとしたオブジェクトです。例えば、顔検出では、目の位置、鼻の位置、口の位置などが、このLandmarkオブジェクトで表現される。

Type

Typeは、パーツを表すコードです。顔検出の結果となるデータの、Landmarkオブジェクトのtypeプロパティに含まれます。種類は下記の通りです。

Position

Positionは、3次元の位置情報を含むオブジェクトで、X座標(画像の左端から右方向への距離)、Y座標(画像の上端から下方向への距離)、そしてZ座標(手前、前後の距離)で表現されます。距離はピクセル値で、画像のオリジナルサイズに準じた計算となっています。

Likelihood

Likelihoodは、程度、度合いを示すコードです。セーフサーチ時の有害レベル、顔検出時の感情レベルなど、様々なデータのレベルを表現するために用いられます。

LandmarkAnnotations

landmarkAnnotationsは、ランドマーク検出(LANDMARK_DETECTION)の結果を含むオブジェクトです。

LogoAnnotations

LogoAnnotationsは、ロゴ検出(LOGO_DETECTION)の結果を含むオブジェクトです。

LabelAnnotations

LabelAnnotationsは、ラベル検出(LABEL_DETECTION)の結果を含むオブジェクトです。

TextAnnotations

textAnnotationsは、文字検出(TEXT_DETECTION)の結果を含むオブジェクトです。

SafeSearchAnnotation

SafeSearchAnnotationは、有害画像検出(SAFE_SEARCH_DETECTION)の結果を含むオブジェクトです。各項目の判定結果は、Likelihoodで表現される。

ImagePropertiesAnnotation

ImagePropertiesAnnotationは、色解析(IMAGE_PROPERTIES)の結果を含むオブジェクトです。2016年2月現在、その内容はdominantColorsオブジェクトの1種類のみです。

DominantColors

DominantColorsは、その画像の配色を支配する色の情報を含むオブジェクトです。その内容はcolorsオブジェクトで構成されています。

Colors

Colorsは、色の情報を含むオブジェクトです。含む色の分だけ、colorオブジェクトが配列で含まれます。例えば、3種類の色情報を含むcolorsオブジェクトは下記の通りです。

Color

Colorは、色の内容を含むオブジェクトで、RGBのred、green、blueで構成されます。