[IBM Cloud] IT超初心者がIBM CloudのICOSでAPIコールしてみた

はじめに

文系学部卒・IT未経験新入社員・IBM Cloud初心者である筆者が、先輩に「ICOSでAPIコールしてみて」と言われ、わからないまま進めた奮闘記録を備忘録として残してみました。

進め方はこちらの記事を参考にしています。

そもそもAPIコールとは？

API (Application Programming Interface) とは、
ソフトウェアやプログラム同士を繋ぐインターフェースのことです。
APIがあることで、複数のアプリやサービス同士の連携が可能になります。

日常生活で例えると、レストラン予約アプリのように複数のお店の情報を集め、アプリ内で予約までを完了させる仕組みは、様々なデータソースがAPIで連携しあうことで成り立っています。APIがなければ、データソースが連携していないため、私たちが一つ一つのお店の情報をGoogleで調べ、電話で空きを確認して予約する必要があります。

そんな便利なAPIを提供する窓口のことをAPIエンドポイントと言います。このAPIエンドポイントに向かってリクエストを送り、レスポンスが帰ってくることでAPIが構成されます。

そして、このリクエストを送ることを「APIコール」と言います（APIリクエスト・API呼び出しとも言う）

※以下の記事を参考にしています。

APIコールには鍵と認証が必要

認証が重要

APIコールを行う際は、認証の仕組みが重要です。
この仕組みがなければ、悪意のあるユーザーに重要なデータが渡ってしまうからです。PaaS系のクラウドサービスを利用する際の一般的な認証の仕組みはアクセストークンを用いた認証です。

その中でも今回は、Bearer(ベアラー)認証を行います。
Bearerとは英語で「所有者」と言う意味を表すそうで、Bearer認証は、Bearer tokenを持っている人に対してアクセスを許可する認証の仕組みです。

つまり、Bearer tokenを持っていると、適切なユーザーであると認証され、APIコールを実施することが可能になります。

認証のためには鍵が必要

そして、そのBeare tokenを取得するためには、まず「APIキー」と呼ばれる鍵が必要です。

APIキーとは、そのリクエストがどこから送られてきたものか（＝アクセス元）を識別するための一意な文字列です。これにより、APIの提供側は「どのアプリケーションやツール、あるいはユーザーがこのAPIを使おうとしているのか」を判断できます。

IBM Cloudの場合、APIキーは事前にIAM (IBM Cloud Identity and Access Management)から取得できます。IAMがAPIキーを発行し、そのAPIキーが、IBM Cloudのユーザーに対して割り当てられます。

よって、ICOSでAPIコールをする際には、

①IBM Cloud Portal上でAPIキーを取得する（初回のみ）
②APIキーを使ってBearer tokenを取得（Bearer tokenは有効期限があるので定期的に行う必要がある）
③Bearer tokenを使ってBearer認証をクリア（毎回）

この３つのステップが必要となります。

※以下の記事を参考にしています。

APIコールを実施してみよう

目指すゴール

IBM Cloud のICOSの自分のバケットに、APIで画像をアップロードしたい！

ステップ

今回は４つのステップに沿って進めていきます。（下の図をご参照ください）

1. IBM Cloud Portal上でAPIキーを取得する
2. IAMに対してAPIキーを用いてアクセストークン(今回はBearerトークン)を取得
3. 取得したトークンを用いて認証(今回はBearer認証)を通過し、ICOSに資料をアップロード
4. 確認する

1. IBM Cloud Portal上でAPIキーを取得する

APIキーはIBM CloudのIAM (IBM Cloud Identity and Access Management)から取得できます。

こちらの記事を参考にしていただくとわかりやすいと思います。

取得方法を簡単に説明すると以下のようになります。

①IBM Cloud Potalにログイン > Manage > Access(IAM)
②左側のハンバーガーメニューから、「IBM Cloud API Keys」を選択
※漏洩対策・セッションの作成はデフォルトのままにした
※作成したAPI keyは300秒で消えてしまうから急いでメモ_φ(･_･

2. IAMに対してAPIキーを用いてアクセストークン(今回はBearerトークン)を取得

1.で取得したAPIキーを入力し、Bearer tokenを取得する下のコマンドを実行する。※[AAA]とある場合、実際にコマンドとして書くのはAAAのみ。

curl -k -X POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Accept: application/json" \
--data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
--data-urlencode "apikey=[上記で作成したapikey]" "https://iam.cloud.ibm.com/identity/token"

※IAMのエンドポイント: https://iam.cloud.ibm.com/identity/token

実際に入力した画面はこちら

すると、膨大な量の文字列が出てくる。。。
”access_token"の直後の””の中がBearer token
【例】 {"access_token":"eyJraW　〜〜省略〜〜　SMU1SnQt36JLJPg", “ ~~~~”}の場合、「eyJraW　〜〜省略〜〜　SMU1SnQt36JLJPg 」がBearer token

これで、Bearer tokenの取得は完了。

【追記】APIを用いてアクセストークンを取得する方法
①IBM CloudにAPIでログイン: ibmcloud login --apikey [ここにAPIkeyを入力]
②ibmcloud iam oauth-tokensと入力するとBearerトークンが表示される

③下のコマンドを入力 (Access token という名前の環境変数にコマンドを保存する）

export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | head -n 1 | awk '{print $4}'`

④echo $ACCESS_TOKENとコマンドを打つと、Bearerトークンが表示される

step3のようなコマンドを入力する際、この方法を使うことで、毎回手動でBearerトークンをコピー＆ペーストする手間を省くことができます。

3. 取得したトークンを用いて認証(今回はBearer認証)を通過し、ICOSに資料をアップロード

最後に、2.で得たBearer tokenを使って下記コマンドを実行する。

curl -X PUT https://[自分のbucket名].[ICOSのエンドポイント]/[Cloud上に表示したいファイル名] \
-H "x-amz-acl: public-read" \
-H "Authorization: Bearer [取得した自分のBeare token]" \
-H "Content-Type: [MIMEタイプ]" \
-T [ローカルファイルのパス]

このフォーマットを参考に私が実際に入力したコマンドはこちら

curl -X PUT https://バケット名.s3.jp-tok.cloud-object-storage.appdomain.cloud/cloud.jpeg \
-H "x-amz-acl: public-read" \
-H "Authorization: Bearer XXXXXXXXX" \
-H "Content-Type: image/jpeg" \
-T/Users/AAAAA/Downloads/ibm---cloud.jpeg

これでAPIコールは完了！
とはいえ、初めはコマンドの内容がわからず何を入力すれば良いか全くわからなかったので、次の【補足】で一つ一つ解説します。

【補足】Curlコマンドに含まれるオプションの説明

curl: HTTPリクエストを送るコマンド。←これでAPIをよびだす！
-X PUT : HTTPのリクエストメソッドのひとつ。主にサーバーにデータ（ファイルなど）をアップロード・更新するために使われる。
https://[自分のbucket名].[ICOS エンドポイント}/[表示させたいファイル名] :アップロード先のURL。アップロード後、このURLでファイルにアクセスできます。
*ICOSのエンドポイントは s3.jp-tok.cloud-object-storage.appdomain.cloud
*エンドポイントに関する詳細はこちら
https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints

-H "x-amz-acl: public-read" ：アップロードしたファイルを「公開読み取り可能」にする設定
-H "Authorization: Bearer [取得した自分のBeare token]": 認証情報
-H "Content-Type: [MIMEタイプ]"：ファイルのタイプのこと。アップロードするファイルの種類（例：画像か、テキストか）をサーバーに伝えるために必要。下記の表をご参照ください

• -T [ ファイル名]：アップロードするローカルファイルのパス名

[補足]
ちなみに、今回はICOSにAPIコールをしましたが、ICOS以外のIBM Cloudのソリューション（例:Db2など）に対しても、同じBearerトークンを使ってAPIコールすることができます。

これは、IBM CloudのサービスがIAMと連携しており、IAMが発行したトークンを使った認証を受け入れるポリシーを持っているからです。つまり、今回のステップ２までは同じで、ステップ３のURLの部分を、対象サービスのエンドポイントに変更することで、他のサービスにもアクセスできるということになります。

4．確認してみよう

最後に、ICOSのバケットに写真がアップロードされているか確認してみましょう。

【方法１】IBM CloudのUIで確認

IBM Cloudにログインし、ICOSのバケットの中を確認してみます。cloud.jpegが存在することが確認できたので成功！

【方法２】APIでHEADリクエストを送信して確認

もっと簡単に調べるコマンドがあるかもしれませんが、、このコマンドで調べてみました。

curl -I -X HEAD  https://[自分のbucket名].[ICOSのエンドポイント]/[Cloud上に表示したいファイル名]\
  -H "Authorization: Bearer [取得したBearerトークン]"

-I：ヘッダーだけを取得（HEADと同じ意味）
-X HEAD：HTTPリクエストの一つのヘッドメソッド。指定したリソースのヘッダー情報を取得できる。（中身は取得できない）
-H "Authorization: Bearer [取得したBearerトークン]：Bearerトークンを使った認証

これを実行し、下の写真のように「OK」と詳細が出た場合、バケットの中に指定したファイルが存在することがわかります。

存在しない（＝アップロードできていない）場合はOKではなくエラーが出ます。