こんにちは、クロスパワーの佐々木です。
とうとう私にも後輩ができまして、彼らの追い上げに焦る毎日です。
全くもって竹のような後輩です。
さて、以前Amplifyについてざっくりと書いたのですが、
AWS AppSyncについては、あまり馴染みが無い方も多いのではないかと思い、入門的な記事を書くことにいたしました。
【対象者】
〇 AWS AppSyncを最低限使えるようになりたい方
〇 AWS AppSync, GraphQL, DynamoDBを知らない
〇 竹のような後輩に焦りを感じている
AWS AppSyncとは
REST APIとは違う、GraphQLというAPI仕様を用いて「柔軟なAPI」を提供するマネジメントサービスです。
何が柔軟かと言えば、リクエストが来たらリソースを返すだけではなく、リクエストに応じてLambdaで処理を実行したり、HTTPリクエストをすることも可能なのです。
似たような機能を持つAPI Gatewayをご存じな方は、この二つの違いが気になるかもしれませんが、これらの違いは、ほぼ「REST API と GraphQL APIの違い」に置き換えられます。
今回はこの違いについては深堀しませんので、興味がある方は調べてみてください。
※APIキーを使わなくても…
通常APIにはAPIキーが必要ですが、AWS AppSyncならば
アプリケーションのユーザー認証でリソースにアクセスすることもできます。
(AWS Cognitoとの連携による)
前知識
そもそもAWS AppSyncがどういう仕組みになっているか理解する必要がありますね。
上図のようなイメージでAWS AppSyncのAPIは機能します。
ここで登場する4つの役割についてざっくりと説明いたします
▶ リソース
APIのアクションの対象です。例えばDBのレコードを取得/更新したりできます。
しかし、リソースに選択できるものは幅広く、DynamoDB / Lambda / HTTPリクエスト(外部のAPI) などが選択できます。
▶ リゾルバー
DBに対してどのような処理をするのか(CreateやPutなど)、処理内容を記載した関数群になります。
下記のようにリソースの一行動に対して一つのリゾルバが必要になります。
▶ スキーマ
型を宣言するだけの、JSONのようなテキスト(ここに処理内容は記載しません)
ここではメソッドだけではなく、フィールドとその中の変数型なども定義します。
DynamoDBではテーブル定義が無く、自由なレコードを作成できてしまうので、ここでデータの形式を定義します。
また、メソッドにはそれぞれ「処理内容が記載されたリゾルバー」をアタッチする。
▶ クエリ
スキーマで定義した関数を呼び出す箇所です。
アプリケーション内で定義して、ユーザーがAPI通信を発火、データを取得します。
入門実践
今回はGraphQLの動作に慣れるために下記のことをやっていきます。
(前編)
1. クエリを理解して、データを作成/取得
(後編)
2. DynamoDBのテーブルを作成して、クエリから作成/取得する
3. リゾルバの改造
前準備
今回は手軽にサンプルプロジェクトから作成していきましょう。
これによっりサンプルの「DynamoDBテーブル」や「スキーマ」、「リゾルバー」を勝手に作ってくれます。
(AWS AppSyncからDynamoDBにアクセスするためのロールも作成される)
手順
以上、手軽ですね。
これで初めに表示される、「クエリ」のページにてリクエストを試すことができます。
ここからはクエリについて理解を深めていきましょう。
1. クエリを理解して、データを作成/取得
AWS AppSyncでのクエリの使い方
既に下記のような2つのメソッドが書かれていると思います。
一つ目：イベントを作成するメソッド
二つ目：イベントを一覧取得するメソッド
mutation CreateEvent {
createEvent(
name: "My First Event"
when: "Today"
where: "My House"
description: "Very first event"
) {
id
name
}
}
query ListEvents {
listEvents {
items {
id
name
}
}
}
実際に実行してみましょう。
「▶ボタン」を押すとメソッドが一覧で出るので、ここで「CreateEvent」を押すことでイベントの作成を実行できます。何個か作成しましょう。
同じ要領でListEventsを実行すると、右画面に結果が出るはずです。
今はまだListEventsで表示される情報は一部なので、idとname以外の情報も表示しましょう。
query ListEvents { listEvents { items { id name when where } } }
上記のように追記、実行することで結果に、whenとwhereが追加できます。
※エディタ内でCtrl+Spaceすると候補を出せます
また、右上の「Documentos」からどのようなメソッドがあるのか、またどんな型なのかも確認することができます。
※スキーマに定義されたもの
クエリの理解
Documentosを見れば分かる通り、クエリには下記の３種類があります。
- query ... データ取得
- mutation ... データ作成/更新/削除
- subscription ... イベントの購読
（データの更新時にその情報を受け取るための、存続期間の長い接続）
クエリは上記のいずれかを使って定義します。
例えば、DocumentosのQueryをクリックして開くと、下記のようなメソッドがあると思います。
getEvent(id: ID!): Event Get a single event by id.
これは引数に「イベントのid(ID型)」をとり、戻り値はEvent型であることを表しています。※「!」は必須な引数であることを表しています
さらにIDやEventをクリックして開くと、その型の詳細を確認できます。
このgetEventを使ってみましょう。
query MyGetEvents { getEvent( id:"bc55390a-3cc9-4af6-b5d6-54ed3369ef9d" ) { name description } }
getEventはQueryのメソッドなので、好きな関数名の先頭にquery型という宣言をしておきましょう。
この関数単位がクエリの実行単位になります。
複数getEventを並べたり、同時にcreateしたりできます。
また、idにはListEventsで得たidを指定します。
関数の中身には、戻り値のどれを取得するのか指定します。
今回はEvent型のdocumentosを参照して、nameとdescriptionを指定しました。
実行して確認しましょう。
また、mutationとsubscriptionも同様の手順でクエリを作成することができます。(subscriptionはAWS AppSync上ではテストできませんでした)
少し違和感があるかもしれませんが、mutationでもqueryと同様に戻り値があるので指定しましょう。
おまけ：PostmanからAWS AppSyncにリクエスト
GraphQLでリクエストする場合には、REST APIとは違ってURLは一つです。
(AWS AppSyncコンソールの設定より取得)
また、どうやって取得したいリソースをリクエストするのかといえば、
「クエリ」をリクエストボディに記述することでできます。
ただ、生のテキストで記述をしてもエラーが返ってきてしまうので
下図のようにGraphQLを選択してクエリを記述しましょう。
あとはAPIキーを設定する必要があります。
APIキーはAWS AppSyncコンソール上で「設定」を開くとコピーすることができます。
これをPostman上ではヘッダーとして、
KEY : x-api-key
VALUE : {APIキー}
のように設定します。
※他にもこのような方法でリクエストしている方もいらっしゃいましたので参考までに。
少し長くなりましたので、この続きは後編で...
AWS AppSyncでGraphQLへの入門が「easy」になる(後編)
