AWS の API を理解しよう !

初級編 ~ API の仕組みと利用方法を理解しよう

2022-09-02

How to be a Developer

Author : 杉本圭太

はてブ »

こんにちは ! テクニカルトレーナーの杉本圭太です。
最近読んで面白かった漫画は「最後の秘境東京藝大―天才たちのカオスな日常―」です。

私は業務でお客様に AWS の様々なトレーニングを提供しているのですが、最近はエンジニア以外の方でも「業務でクラウドに関わるので AWS を学習したい」という方が多くいらっしゃり、多様な職種の方にトレーニングを受けていただく機会が増えています。そしてトレーニングの中で AWS の特徴の 1 つとして「AWS のサービスは API で操作できる」と紹介することがあるのですが、「API で操作するというのがいまいちピンと来ない」という声をいただくことが何度かありました。

そこで今回は ”初級編” として、「API とは何なのか」を喩えを交えながら解説し、「AWS ではどのように API を利用するのか ?」について、少し技術的な知識にも踏み込みながら説明します !

さ・ら・に、AWS の API は知ってるよという方向けに、知識の確認や腕試しにもなる “クイズ” を最後に用意してありますので、興味ある方はそちらだけでもチャレンジしてみてください o(*ﾟ∀ﾟ*)o

また ”中級編” として AWS で API を利用することは知ってるけど、普段何気なく利用している方が、「へぇ、なるほど !」と思ってもらえるような、認証やツールの仕組みを紹介する内容を盛り込んだも記事も次回予定していますのでお楽しみに !

このシリーズ記事のその他の記事はこちら

はじめに

この記事のテーマである「AWS のサービスは API で操作できる」というのは「クラウド (クラウドサービス) とは ?」で以下のように書かれています。

AWS では、サーバー、ストレージ、ネットワーク等の主要機能は API 経由での操作が可能です。

そもそも API とは何なのでしょうか ? そして AWS のサービスを API で操作できることにどんなメリットがあるのでしょうか ? また、AWS は利用しているけど、API を使っていると感じていない方もいらっしゃるかもしれませんが、それはなぜでしょうか ?

これらの疑問を 1 つでも持っている方は、今回の記事を読んで AWS の API について理解を深めていきましょう !

それでは "初級編" スタートです !

API とは ?

まずは API と言われてもピンとこない方へ、どんなものかイメージしやすくなるようなお話をします。API とは何か知ってるよという方は次の「AWS で API を利用するメリット」へお進みください !

API は Web サービスなどのアプリケーションなどで利用されるものであり、「API とは - API ビギナーズガイド」では以下の説明がされています。

API は、2 つのソフトウェアコンポーネントが一連の定義とプロトコルを使用して相互に通信できるようにするメカニズムです。

私はこの言葉を少し言い換えて、API は「サービスを提供している相手に、決められた形式で依頼を送ると、決められた形式の結果が返ってくる仕組み」と表現することがあります。

これを身近なものに喩えてみます。みなさんが家でピザが食べたいときは「ピザ屋さんに、そのお店のメニューから “シーフードピザの L サイズ、トッピングはタバスコで“ と電話で注文をすると、頼んだ商品が配達される」と思いますが、実はこの仕組みも API の特徴に似た部分があります。

このピザが配達される仕組みを「ピザ屋さん (サービスを提供している相手) に、そのお店のメニューから “シーフードピザの L サイズ・トッピングはタバスコで“ と電話で注文 (決められた形式で依頼) をすると、頼んだ商品が配達される (決められた形式の結果が返ってくる)」という表現に当てはめてみると、API の説明になんとなく似てませんか ?

API とはソフトウェア同士 (もしくはアプリケーション同士) が、このようにサービスを提供している相手に依頼をして、結果を受け取る仕組みといったところでしょうか。

当たり前ですがお蕎麦屋さんにピザの注文をしたり、注文するピザ屋さんにないメニューを頼んでも注文は成立しません。電話を利用せずに、いきなりお店に向かって注文を叫んでももちろん商品は届きません。これは依頼先や依頼を伝える方法が正しくないからですが、API を利用する場合も同様にサービスの依頼先や依頼を伝える方法などは重要な要素です。

ソフトウェアの場合、依頼を伝える方法は「お互いが通信して内容を理解するための決まりごと」を使うことで実現させています。この「決まりごと」を「プロトコル」と言います。API の説明の中でもプロトコルという言葉が出ていましたが、ピザの注文の場合「電話という通信手段で、お互いの共通認識であるメニューから注文する」というプロトコルがあるから相手に依頼が正しく伝わる、と考えると「プロトコル」の役割を理解しやすいかもしれません。これはまた後ほどお話しします。

では AWS で API を利用すると何ができるかを考えてみます。AWS の場合はコンピューティング・ネットワーク・ストレージなど多くのカテゴリのサービスを提供しています。そのため利用者は API を利用して「自分達専用の仮想ネットワークを作成してね」「CPU 1 つ、メモリ 2 GB 、ストレージが 20 GB の Linux サーバーを用意してね」などの依頼を端末からインターネットで AWS へ送ることができ、AWS は依頼に応じた処理 (例えば利用できるネットワークやサーバーなどのリソースの確保) をして結果を返してくれます。

ここで AWS の API で利用する「プロトコル」は何でしょうか。先ほどのピザ屋さんの喩えではプロトコルにあたるものは「電話という通信手段でメニューから注文するという決まりごと」でしたが、インターネットという通信手段を利用した API では HTTP と呼ばれるプロトコル (ネットワークで情報を送り合うときに利用できる決まりごとの 1 つ) を利用することが多く、AWS の API も HTTP を利用します。スマホや PC のブラウザでインターネットする時も HTTP は利用されていますね !

HTTP を利用した API がどんなものかですが、例えばもし、天気予報を教えてくれる Web サービス (例：weather.example.com) が提供している API があるとします。その場合、以下のように URL へ知りたい都市の天気予報を指定してリクエストすると、レスポンスとして天気予報の結果が返ってくるイメージです。

▼ とある API のリクエストの例

http://weather.example.com/forecast?country=jp&city=tokyo

▼ とある API のレスポンスの例

{"date": "2022/09/01", "country": "jp", "city": "tokyo", "forecasts": "sunny"}

この HTTP というのは、クエリ文字列と呼ばれるパラメーターなどを含む URL、メソッドやヘッダー、ボディと呼ばれる要素で構成されたテキスト情報を HTTP リクエストと HTTP レスポンスの形式で送り合います。今すぐ全てを理解する必要はありませんので、まずは以下のように「HTTP は決まった形式で文字情報をやり取りしてるんだ」とだけ認識していただければ OK です d(`･◡･´)b

引用元 : https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages

今回のポイントとして押さえていただきたいのは、 HTTP を利用した API では「サービスを提供している相手」を指定する方法がURL (例 : http://service.example.com/) であり、「依頼」を HTTP リクエスト、「結果」を HTTP レスポンスとして、文字情報を送ったり受け取ったりしているということです。

ここまでが API の説明と、API でよく利用される HTTP というプロトコルの簡単な紹介でした。(★ HTTP についてより詳しく知りたい方はこちらをご確認ください)

AWS で API を利用するメリット

では AWS のサービスを API で操作できると、何が嬉しいのでしょうか ?

従来であれば、ある程度大きなシステムを構築する場合は、データセンターにサーバーコンピューターやストレージを用意して OS をインストールし、ネットワークのケーブル配線とルーターの設定などを手動で行う必要がありました。(このようにシステムを構築する人達がハードウェアの用意や運用・保守をすることを「オンプレミス」とも呼びます。)

しかし AWS は API を利用できるようにしているクラウドサービスであるため、インターネットに繋がった端末さえあれば AWS が用意するコンピューティング・ネットワーク・ストレージなど多くのカテゴリのサービスを API で操作することで、手動の作業なしで自分達に必要な専用の仮想ネットワークの構築・サーバーやストレージの調達・システム開発に役立つサービスとの連携ができ、数分でシステムを構築することも可能です。

AWS が用意しているサービスには以下のようなものがあります。

仮想サーバーを提供する「Amazon Elastic Compute Cloud (EC2)」
プライベートなネットワークを提供する「Amazon Virtual Private Cloud (VPC)」
オブジェクトストレージを提供する「Amazon Simple Storage Service (S3)」
フルマネージドなデータベースを提供する「Amazon DynamoDB」

AWS の API を利用するための基本知識

※ これ以降はしばらく AWS の知識や技術的な知識を踏まえた内容も含まれるので、少し難しいなと感じる方はさらっと読み流して「API をより楽に利用するために」へ進んでいただいて大丈夫です ٩(๑･∀･)۶

ではここから、AWS の API を利用するための必要な基本知識をお伝えします。
ポイントは「リソース」と「サービスエンドポイント」と「アクション (Actions)」です !

リソース

AWS ではよく「リソースが〜」という表現が出てきます。先ほどの AWS で API を利用するメリットでもお伝えした「自分達に必要な専用の仮想ネットワークの構築・サーバーやストレージの調達」は、「AWS のネットワーク・サーバー・ストレージなどのサービスからリソースを確保する」とも言ったりします。

AWS の「リソース」という言葉はこちらのドキュメントから抜粋すると、以下のように書かれています。

AWS では、リソースはユーザーが操作できるエンティティです。

これは「AWS のサービスからみなさんが確保して利用できる部分」と考えるとイメージがつきやすいかもしれません。

AWS のサービスごとに多種多様なリソースがありますが、以下によく利用するものを挙げてみました。

サービス	リソースの例
EC2	インスタンス (仮想サーバー 1 台を 1 インスタンスという単位で呼ぶ)
VPC	VPC (サービス名ではなく、リージョンやプライベート IP の範囲を指定したお客様専用の仮想ネットワーク) やサブネット
S3	データの入れ物であるバケットや、バケットに格納したデータであるオブジェクト
DynamoDB	データベースのテーブルや、テーブルの中のデータである項目

文脈にもよりますが、今回の記事の中では AWS の「リソース」と出てきた場合はこちらの意味で捉えてください φ(•ᴗ•๑)

サービスエンドポイント

API ではサービスを提供している地点を「エンドポイント」と呼び、HTTP を利用した場合は URL のドメイン部分 (例 : service.example.com) が API の「エンドポイント」として表されることもあります。
AWS では EC2 や S3 などサービスごとにエンドポイントが定義されており、これを「サービスエンドポイント」と呼びます。

リージョンがサポートされている (= リージョンを選択して利用する) サービスの場合、サービスエンドポイントにプロトコルを合わせた以下の形式が API で利用されます。(★サービスごとに利用できるエンドポイント一覧はこちらをどうぞ !)

protocol://service-code.region-code.amazonaws.com

protocol:// の部分は AWS の API ではほとんどの場合 https:// (暗号化された HTTP 通信) を利用します。(※ AWS Systems Manager では wss:// を指定して WebSocket というプロトコルを利用することもありますし、推奨はされませんが一部のサービスでは http:// を利用することも現時点では可能です）
service-code と region-code の部分は利用したいサービスとリージョンを選択します。

たとえば https://ec2.ap-northeast-1.amazonaws.com は、アジアパシフィック (東京) リージョンの EC2 のエンドポイントに HTTPS のプロトコルで通信することを表します。

また、リージョンがサポートされていない (= リージョンを選択せずに利用する) 一部のサービスのエンドポイントには region-code の部分が含まれないため、例えば AWS Identity and Access Management (IAM) のエンドポイントに HTTPS で通信する場合は https://iam.amazonaws.com が利用されます。

アクション (Actions)

各サービスエンドポイントごとにどのような API が利用できるかは、サービスごとの API リファレンスというドキュメントで確認できます。そして API リファレンスには、役割ごとに名前が付けられた API が Actions として一覧化されています。(★各サービスの API リファレンスはこちらからどうぞ !)

例えば、EC2 というサービスで利用できる API は Amazon EC2 actions に一覧があります。インスタンスを起動する場合はこの中の RunInstances という API を利用します。RunInstances のドキュメントを読むと、利用するためのリクエストパラメーターとレスポンスの詳細が記載されており、起動するインスタンスの CPU やメモリの値を指定する場合は InstanceType を利用すれば良いことがわかります。

ここまでを整理すると、AWS の API を利用する場合は、PC などインターネットに繋がっている端末から「利用したい AWS サービスのエンドポイント」へ「利用したいアクションを選択して、定められた形式でリクエスト」し「結果をレスポンスとして受け取り」ます。

EC2 のインスタンス起動をするため、RunInstances の API をリクエストした場合を以下のような図にしてみました。①で EC2 というサービスに EC2 インスタンスの起動をリクエストすると、②でサービスエンドポイントはそれを受け取って依頼されたリソースであるインスタンスを起動します。そして③で起動が成功したのか失敗したのか、成功した場合は確保したリソースの情報をレスポンスとして返すという流れです。

処理のフローだけではなく curl コマンドなどで API を利用するとどのような結果が返ってくるかの例を見てみましょう。
※ 実際には「誰からのリクエストか」「改ざんされていないか」などを判断するための署名情報なども必要ですが、見やすさのためいくつかの情報を省略しています。

▼ RunInstances のリクエストの例

curl https://ec2.ap-northeast-1.amazonaws.com/?Action=RunInstances\
&ImageId=ami-xxxxxxxxxxxxxxxxx\
&MaxCount=1\
&MinCount=1\
&AUTHPARAMS...

▼ RunInstances のレスポンスの例

<?xml version="1.0" encoding="UTF-8"?>
<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
    <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
    <reservationId>r-xxxxxxxxxxxxxxxxx</reservationId>
    <ownerId>123456789012</ownerId>
    <groupSet/>
    <instancesSet>
        <item>
            <instanceId>i-xxxxxxxxxxxxxxxxx</instanceId>
            <imageId>ami-xxxxxxxxxxxxxxxxx</imageId>
            <instanceState>
                <code>0</code>
                <name>pending</name>
            </instanceState>
            <privateDnsName>ip-10-0-0-100.ap-northeast-1.compute.internal</privateDnsName>
            <instanceType>m1.small</instanceType>
            <launchTime>2022-09-01T00::00.000Z</launchTime>
......
        </item>
    </instancesSet>
</RunInstancesResponse>

今回の API では上記の例のように GET メソッドを利用して、クエリ文字列に必要な情報を入れて送ると XML が返ってきましたが、API ごとにリクエストとレスポンスの形式は様々です。例えば S3 の CreateBucket ではリクエストやレスポンスのボディに XML を利用したり、DynamoDB の CreateTable は json を利用します。

このように API の利用方法については理解できましたが、仕組みを知ったからこそ以下のように感じるかもしれません。

レスポンスには情報がたくさんありすぎて、自分に必要な部分だけを抜き出すのが面倒だな
API ごとに形式の一貫性がないと少し不便かも
そもそも利用するために知らないといけないことが多い

しかしみなさんは AWS を利用するときにこのように複雑なリクエストを送って、複雑な形式のレスポンスの情報をそのまま利用してはいないはずです。それはなぜかを次で紹介します !

API をより楽に利用するために

ここまで AWS の API について説明をしてきましたが、実際に AWS を利用する場合のほとんどは以下の方法です。

AWS マネジメントコンソールで画面を操作する。(ブラウザでボタンをポチッと押していくやつです !)

クリックすると拡大します

AWS コマンドラインインターフェイス (AWS CLI) でコマンドを入力する。(テレビドラマや映画で、ハッカーが黒い画面にカタカタ入力しているようなツールです !)

クリックすると拡大します

AWS SDK を利用したプログラムを書いて実行する。(Java や Python などでコードを書いたアプリケーションから AWS のサービスを操作できます !)

クリックすると拡大します

このようにマネジメントコンソールや CLI、SDK のツールを利用して AWS を操作した場合でも API が利用されているのですが、ここまで紹介したような、「アクションごとにリクエストやレスポンスがどのような形式なのかを意識して HTTPS で通信する」作業をみなさんはやっていません。それはこれらのツールがそれぞれの機能で、利用するアクションごとに適した形式で HTTP リクエストを送り、HTTP レスポンスの内容から必要な部分を抜き出して見やすく表示してくれるからです。ありがたいですね！API を直接利用するという、めちゃめちゃ厳しい壁も乗り越える力が湧いてきます (*´ｰ`*人)

それぞれのツールを使って AWS を利用するフローも図にしてみました。これがみなさんが API を意識せずに AWS を利用しているカラクリです !

まとめ

以上、AWS のサービスを API で操作する基本について紹介しました !

ではここまでの内容を知っていれば AWS の API は誰でも勝手に使えるのかというと、そうではありません。実際に AWS の API を利用するためには、どのアカウントの誰がリソースを利用するかなどを制御するために、認証情報が必要になってきます。この認証情報を API に追加する方法や、他にもマネジメントコンソールや CLI、SDK が API をどのように送っているかについてなどを、次回の “中級編” でご紹介しますのでお楽しみに !

クイズ

もしかすると知っていれば役に立つかもしれない、そんな内容のクイズを、今回の記事の中で紹介したドキュメントを隅々まで読めばわかる範囲で作ってみました ! 問題の下をスクロールすると正解がありますので、少し考えてから確認してみてください !

問題

1. リージョンがサポートされている (= リージョンを選択して利用する) サービスでも、サービスエンドポイントにリージョンを含めないことも可能です (例 : rds.amazonaws.com)。この場合、サービスエンドポイントのリージョンはどこになるでしょうか？

2. リージョンの一覧が取得できる DescribeRegions という API があるのですが、これはどのサービスのエンドポイントに対して実行できるアクションでしょうか ?

3. Amazon CloudFront と AWS Global Accelerator のサービスエンドポイントは cloudfront.amazonaws.com と globalaccelerator.amazonaws.com であり、region-code が含まれないのですが、サービスエンドポイントのページを確認すると 1 つのリージョンだけが記載されています。それぞれどのリージョンでしょうか ?

↓ (正解はこちら) ↓

正解

1. us-east-1
★記載はこちら

Amazon EC2 などの他のサービスではリージョンがサポートされていますが、リージョンを含まないエンドポイント (例: https://ec2.amazonaws.com) を指定できます。リージョンを含まないエンドポイントを使用する場合、AWS は、API コールのデフォルトリージョンである米国東部 (バージニア北部) (us-east-1) に Amazon EC2 リクエストをルーティングします。

2. EC2
★ DescribeRegions の API リファレンスはこちら
 ★ AWS のリージョン管理についてのドキュメントはこちら

3. CloudFront は us-east-1、Global Accelerator は us-west-2
★ Amazon CloudFront のサービスエンドポイントはこちら
 ★ AWS Global Accelerator のサービスエンドポイントはこちら

全問正解した方おめでとうございます 👏 👏 👏
残念ながら景品はありませんが、次回の記事でもクイズを予定しています !
クイズにできそうな内容があれば、こっそり私に教えてください ^^