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

Adobe I/O Corporate

この投稿について

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の場合

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

アクセストークンの追加

アセットの購入やユーザー・組織に紐づいたアセット情報の取得に使用する全ての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の場合

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

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の場合

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

今回は、キーワードを”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を導入する方へ本投稿が少しでもお役に立てれば幸いです。

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

関連リンク

デベロッパーブログ記事一覧

  1. デベロッパー向け技術情報を日本から発信します
  2. Adobe I/Oのアプリケーション開発を始める前に
  3. Adobe Stock APIの紹介
  4. Adobe Stock API: アプリケーションの登録
  5. Adobe IDによるOAuth認証

投稿者

Eiichi Fukushima

POSTED ON 2018.05.30

Products Featured

関連製品はありません

Tags