Adobe Stock API: Stock REST APIリクエスト #AdobeIO

この投稿について

Adobe I/O デベロッパーブログを読んで頂き有り難うございます。Adobe Stockにフォーカスをあて、数回のシリーズに分けてAdobe Stock APIの概要・導入方法・機能説明・APIリクエストの方法を紹介しています。前回の投稿で、Adobe I/O Console上でのAdobe Stock APIを使用をするアプリケーションの登録とクレデンシャル (API KeyとClient Secret)の取得について掲載しました。今回は、そのクレデンシャル情報を利用して、Authorizationヘッダーを含むAPIリクエストについて掲載します。Adobe I/O Consoleの使用法や認証に使用するアクセストークンの取得については、下記のAdobe I/Oブログの記事をご参照ください。

コンテンツ

クレデンシャル情報のストア
Stock REST APIリクエスト
アクセストークンの追加
Search APIの使い方
最後に

クレデンシャル情報のストア

インテグレーションのタイプによって、認証に必要なクレデンシャル情報が下記のように変わります。

API Key: API-Keyのみ
OAuth: APIKey, client secret, redirectURI
Service Account: API key, technical account ID, organization ID, client secret

インテグレーションタイプについては、前回の記事をご参照ください。

※client secretは、取り扱いに注意が必要なクレデンシャルとなります。外部へ流出しないようセキュアな環境にストアしてください。JavaScriptなどのフロントエンドのスクリプトへclient secretを埋め込み等は、避けてください。

Stock REST APIリクエスト

Adobe Stock APIは、REST APIであり、全てのAPIリクエストには、’X-Product’と “X-API-Key’の二つのHTTPヘッダーが含まれます。また、保護されているリソースへアクセスする際には、認証ヘッダーが要求されます。

必須のHTTPヘッダーの例:

X-Product: MyStockApp/1.0
X-API-Key: cba123c9f1194eac8a63cc25c1b9fdr

ユーザーが購入したアセット情報等の保護されたリソースへアクセスする際やAPIを使用してアセットを購入する際は、上記の基本ヘッダーに加え、アクセストークンのヘッダーへの追加が必要です。

早速、APIリクエストを検証してみます。ここでは、curlまたは、REST API検証クライアントツールのPostmanを使用して検証します。

curlの場合

curl "https://stock.adobe.io/Rest/Media/1/Search/Files?locale=en_US&search_parameters%5Bwords%5D=dogs"
-H "X-API-Key: cba123c9f1194eac8a63cc25c1b9fdr"
-H "X-Product: MyStockApp/1.0"

Postmanの場合

https://blog.adobe.com/media_8a05314bdebe77524e3819816786a30b429f3e3a.gif

上記のAPIリクエストの送信後に下記のようなJSONレスポンスが返されれば、APIリクエストの成功です。

https://blog.adobe.com/media_4fa8638ee1a7d87cfa0c6cce2114a2c6240753b8.gif

アクセストークンの追加

アセットの購入やユーザー・組織に紐づいたアセット情報の取得に使用する全てのAPIリクエストは、アクセストークンが要求されます。アクセストークンの生成方法については、Adobe IDによるOAuth認証をご参照ください。生成されたトークンをリクエストヘッダーへ追加することによって認可されたAPIリクエストが可能となります。

例:

Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoY

※ Authorizationヘッダーへ渡す値は、”Bearer” + access tokenになる事に注意してください。

それでは、アクセストークンの検証をしてみます。下記の形式でAPIリクエストを試してください。

curlの場合

curl "https://stock.adobe.io/Rest/Libraries/1/Member/Profile?locale=en_US"
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs....."
-H "X-API-Key:cba123c9f1194eac8a63cc25c1b9fdr"
-H "X-Product: MyStockApp/1.0"

Postmanの場合

https://blogs.adobe.com/japan-conversations/files/2018/05/image2018-4-13_15-10-27.png

上記のAPIリクエストの送信後に下記のようなJSONレスポンスが返されれば、APIリクエストの成功です。

https://blog.adobe.com/media_c5ca2a60f4bf3baab891017acb9902978d2bac13.gif

Search APIの使い方

リクエストヘッダーの構築を学んだので、それを利用して、Adobe Stock REST APIリクエストを試してみましょう。今回は、Adobe Stock APIを代表するSearch APIを紹介します。

アセットの検索をするためには、Stock REST APIのURL(https://stock.adobe.io/Rest)の末尾へ”/Media/1/Search/Files”を追加してエンドポイントを指定し、一つ以上のsearch_parametersをクエリーとして追加する必要があります。主に三つのタスクをクエリーで指定します。

サーチタイプの指定: どのように検索するか選択します。検索は、キーワード、類似イメージ、アセットID、クリエイターID等、様々なキーで検索が可能です。
検索のフィルター: デフォルトでは、検索結果は、画像、動画、ビデオ、テンプレート、3D等のすべてのアセットタイプの情報を返却します。フィルターをすることによって、検索結果を特定の情報だけに絞ることが出来ます。
レスポンスフィールドの設定: レスポンスフィールドを設定しない場合、毎回、デフォルトで設定されたフィールドが返却されます。レスポンスフィールドを設定した場合、返却されるフィールドを指定することが出来ます。

それでは、ここで一つ例を紹介します。

検索例: 検索キーワードを”dogs” にして、検索結果を一件のみを表示する

リクエストURL: https://stock.adobe.io/Rest/Media/1/Search/Files?locale=en_US&search_parameters[words]=dogs&search_parameters[limit]=1

リクエストヘッダー:

GET /Rest/Media/1/Search/Files?locale=en_US&search_parameters[words]=dogs&search_parameters[limit]=1 HTTP/1.1
Host: https://stock.adobe.io
X-Product: MyStockApp/1.0
X-API-Key: cba123c9f1194eac8a63cc25c1b9fdr

このリクエストURLとリクエストヘッダーの情報を使ってSearch APIリクエストを試してみましょう。

curlの場合

curl "https://stock.adobe.io/Rest/Media/1/Search/Files?locale=en_US&search_parameters[words]=dogs&search_parameters[limit]=1"
-H "X-API-Key:cba123c9f1194eac8a63cc25c1b9fdr"
-H "X-Product: MyStockApp/1.0"

Postmanの場合

https://blog.adobe.com/media_fe76e0f771131dbf246f7029ae68f308b7929899.gif

上記のAPIリクエストの送信後に下記のようなJSONレスポンスが返されれば、APIリクエストの成功です。

https://blog.adobe.com/media_ebbd99cf70c2ccbdaa13b9e86dcaea3556edd250.gif

今回は、キーワードを”dogs”に、検索結果を一件にしたいので、下記の二つのsearch_parametersを利用しました。

search_parameters[words]
search_parameters[limit]

検索結果を画像だけ絞りたい場合は、下記のsearch_parametersを指定します。

search_parameters[filters][content_type:photo]=1

このように、search_parametersを指定することにより、様々な検索に対応することが出来ます。指定可能なパラメータについては、Search APIリファレンスをご参照ください。

最後に

数回のシリーズに分けてAdobe Stock APIの概要・導入方法・機能説明・APIリクエストの方法について紹介をしてきましたが、いかがだったでしょうか。今回は、割愛させて頂きましたが、Adobe Stock APIには、License API、Profile API, License History API等、別のAPIも存在します。皆様のユースケースに応じてご活用ください。各APIの詳細に関しては、APIリファレンスをご参照ください。Adobe Stockサービスとの連携にご興味がある方、または、初めてAdobe Stock APIを導入する方へ本投稿が少しでもお役に立てれば幸いです。

最後まで読んで頂き有り難うございました。