GraphQL APIの初心者向けガイド
この記事はMarion Schleiferの以下の記事を翻訳したものです。
こんにちはHasura GraphQL APIを使用してサーバーレスバックエンドを構築する方法を説明します。 GraphQLとその利点を見た後で、API用に新しいテーブルを作成する方法を学びます。 次に、データベースに実際のデータを入れます。 もちろんテーブル間の関係の作り方も紹介します。 最後に、mutationを使ってデータを操作する方法を学びます。 このチュートリアルを進めるにあたりGraphQLに関する知識は必要ありません。
目次
GraphQLについて
Hasuraについて
プロジェクトを作成する
テーブルを作成する
データを挿入
問い合わせ
関係
オブジェクトの関係
配列の関係
多対多の関係
mutation
コミュニティに参加する
GraphQLについて
GraphQLはAPIのための型付けされたクエリ言語です。 Facebook、Twitter、GitHubなど大手企業を含む、ますます多くのテクノロジー企業が、広く使われているREST APIからGraphQLソリューションに移行しています。 RESTのような他のAPIアーキテクチャに対するGraphQLの主な利点は次のとおりです。
- わかりやすいクエリで必要なデータを正確に入手
- 信頼できる結果と役に立つエラーメッセージを入手
- データはサーバーを介さずに直接アクセスされるため、高速で軽量なアプリケーションになる
- 複数のURLを使用せずにリソースを連鎖させることなく、1回のクエリーで複数のリソースを取得
- すべてのデータに1つのエンドポイントを使用し、正しいデータアクセスには入力フィールドを使用できる
- 既存のアプリケーションにGraphQLを簡単に追加できる
これがサンプルクエリです：
これに対応する結果：
ご覧のとおり、クエリは非常に直感的であり結果は予測可能です。 あなたはまさに求めているものを手に入れました。
Webアプリケーションがより複雑になる傾向があるので、速くて簡単に保守できる解決策の必要性が高まっています。 それでGraphQLをチェックするには今がおそらくいい時期です。 しかし、どうやって使うのでしょうか。 自分のサーバーを構築する必要がありますか？ フロントエンドにそれをどのように接続できますか？ 心配しないで、これからそのあたりを紹介しますね。
Hasuraについて
HasuraはDockerコンテナ内で動作するオープンソースのGraphQLエンジンを提供しています。 Hasuraはプロジェクトで作成されたPostgresデータベースに接続します。 Hasura GraphQLを既存のプロジェクトの上で実行することもできます。 これはGraphQLに移行したい場合に特に便利です。移行を少ないステップで実行できるからです。
GraphQL APIをどこにデプロイできるかについては、Heroku、Docker、Digital Ocean、Azure、AWS、およびGoogle Cloudといういくつかのオプションがあります。
プロジェクトの作成
この記事では、Herokuを始めます。 ハリーポッターのAPIを作成します🤓
ダッシュボードで、あなたのapiのための（ユニークな）名前を選択して、「Deploy」ボタンをクリックしてください。
簡単でしたね。 今、あなたが一番下までスクロールすると、あなたはこれを見るでしょう：
「View」をクリックすると、HasuraコンソールはGraphiQLツールで開きます。これもGraphQLを使いやすくするための機能の1つです。 Hasuraコンソールでは、テーブルを作成してクエリをテストできます。 コンソールを見てみましょう。
- これは、apiと対話するために使用される（唯一の）エンドポイントです。 後で外部サービスからデータをポーリングするとき、これはアクセスする必要があるURLです。 ここで確認できますが、GraphQLへのリクエストは常にPOSTリクエストです。
- ここで、リクエストヘッダを追加することができます。 後で（たとえばJWTトークンを使用して）認証を追加したい場合は、ここにヘッダーを追加できます。
- これは、クエリをテストできる分野です。
- ここに結果が表示されます。
- 次にそこに行き、最初のテーブルを作成します。
テーブルの作成
まず、映画を保存するためのテーブルを作成します。 それをしましょう！
- テーブルの名前
- すべてのテーブルにIDを追加することをお勧めします。 整数またはUUIDを使用できます。 UUIDを使います。 オブジェクトを作成するたびにIDを渡す必要はないので、Hasuraは自動的にそれを作成する方法を提供します。
- さらにフィールドを追加する
- テーブルごとに主キーを定義する必要があります。 これが私たちのIDになります。
次の2つのテーブルを作成してください。
characters (id: UUID, name: Text, hair_color: Text, house: Text, wizard: Boolean, birth_year: Integer, patronus: Text)
actors (id: UUID, name: Text, birth_year: Integer, awards: Integer)
データの追加
データを追加してみましょう：
もう1人のcharacterと、2つのmovieと2つのactorを追加します。
クエリ
データができたので、GraphiQLで最初のクエリを実行できます。
このクエリはcharactersテーブルに挿入した2つのcharacterを返します。
クエリに追加できる制約はたくさんあります。 たとえば、特定の数のオブジェクトだけを取得するようにすることができます。 あるいは、特定の条件が満たされているオブジェクトのみを取得します。 これらすべてはHasuraのサイトに分かりやすく紹介されています：https://docs.hasura.io/1.0/graphql/manuals/query/simple-object-query.html
この説明を読んでクエリを微調整することで異なる結果が返ってきます。そのためには、さらにデータを追加する必要があるかもしれません。
関係
現在、互いに独立した3つのテーブルがあります。 クエリを使用すると、movie、character、actorを取得できます。 しかし、私たちは彼らの性格を持つmovieを、またそれぞれのactorを辿ってmovieを検索することはできません。 これを行うためには、関係を定義する必要があります。
関係には、オブジェクトの関係と配列の関係の2種類があります。 オブジェクト関係は1対1の関係です。 たとえば、characterはactorと呼ばれる単一のネストされたリソースを持ちます。 配列の関係は1対多の関係です。 たとえば、movieにはsceneと呼ばれるネストされたリソースの配列があります。
オブジェクト関係
まず、characterとactorの関係をモデル化しましょう。 最初のステップは、charactersテーブルにactor_idを追加することです。
actor_idカラムを追加したら、それを編集しactor_idが実際にactorsテーブルを指す外部キーであることを確認する必要があります。
characterの“ Relationships”タブに移動すると、提案された関係が表示されます。 そうです、Hasuraは外部キーを自動的に検出し、関係について提案をします。 名前として、私たちは “actor”を使います。
次に、charactrをデータベース内の対応するactorに接続します。 charactersテーブルを見てみると、前に作成したcharacterのactor_idがNULLであることがわかります。 データを編集して、これらのcharacterに対応するactorのidを追加できます。
これでcharacterとactorはリンクされました。 こうして一つのクエリでcharacterとactorフィールド両方にアクセスできます。
配列の関係
配列の関係は1対多の関係です。 つまり、テーブルの1つのオブジェクトに別のテーブルの複数のオブジェクトを含めることができます。 この例では、1つの映画に複数のsceneを含めることができ、各sceneは1つのmovieに属します。 sceneには、ID、name、location、およびmovie_idがあります。 それでは、データベースに”scenes”という新しいテーブルを作成しましょう。
すばらしいです！ さて、前と同じように、テーブルを修正してmovie_idを外部キーにする必要があります。
これでmoviesテーブルに移動して”Relationships”をクリックすると、sceneに対して提案される配列の関係がわかります。 この関係を追加して、それを”scene”と呼びましょう。 配列関係を作成するために必要なのはこれだけです。 それをテストするには、scenesテーブルにいくつかの行を挿入します。
多対多の関係
前に説明したように、配列の関係は1対多の関係です。 しかし、movieやcharacterの場合、多対多の関係があります。 1つの映画に複数のcharacterを含めることができ、1つのcharacterを複数の映画に含めることができます。 このシナリオでは、「movie_characters」と呼ぶ結合テーブルを作成する必要があります。このテーブルには、1つの映画と1つのキャラクタの関係を格納できます。 ID、movie_id、およびcharacter_idを持つ”movie_characters”テーブルを作成しましょう。
movie_charactersテーブルの観点からは、moviesテーブルとcharactersテーブルの両方に対するオブジェクトの関係が必要です。 これは、各movie_characterに1つの映画と1つのキャラクタが格納されているためです。
上記のように、movie_characterテーブルのmovie_idとcharacter_idの両方を編集し、それらが外部キーになるようにチェックボックスを選択します。 次に、正しい参照表と参照列を追加してください。 movie_idの場合、参照テーブルは映画であり、character_idの場合、参照テーブルはcharactersです。 両方の参照列の場合、それはIDになります。
“Relationships”タブをクリックすると、オブジェクトの関係について2つの提案が表示されます。 両方を追加して、それらを”movie”と”character”と呼びます。 追加すると、次のようになります。
もちろん、上記のように、データとの関係を作成する必要があります。 IDを使用して、各movieとcharacterの関係についてmovie_charactersテーブルに新しい行を作成します。
やった！テーブルはすべて正しい関係でモデル化されています。 クエリでテストしましょう。
これは素敵ではないですか？ たった1回のクエリで、欲しいフィールドを使っていくつかのリソースにアクセスすることができます。 通常オブジェクト全体が返されるRESTと比較して、クエリを基本要素に減らすことができます。 これにより、APIはより効率的になり、軽量になり、扱いやすくなります。
Mutations
これまでは、APIからデータを取得する方法を学びました。 しかし、新しいデータを追加するのはどうですか？ movieやcharacterを追加したいとときもありますね。 そのためにはmutationが必要です。 mutationはGraphQL APIで使いやすく、クエリと同じように、Hasuraコンソールで試すことができます。
ここで何が起こっているのか説明しましょう。mutationの中では、データベースに格納されているリソースに対して、insert、update、deleteなどのさまざまなメソッドを呼び出すことができます。今回の場合は、新しいmovieを追加します。movieをオブジェクトとして渡す必要があり、1つのmutationに複数のオブジェクトを追加することが可能です。最後に、何かを返す必要があります。この例では新しく作成されたオブジェクトのIDです。
繰り返しになりますが、HasuraのWebサイトにmuatationに関する完璧な説明があります。https://docs.hasura.io/1.0/graphql/manuals/mutations/index.html
例を見て、movieを削除するなど、他のmutationを試してみてください。
今日はここまでです。GraphQLについて楽しく学び、Harry Potter APIをたくさんの新しいテーブルとデータで拡張したいと願っています。何かがはっきりしない場合は、いつでもmarion.schleifer@gmail.comに電子メールを送ったり、Twitterでメッセージを送ったりできます。https://twitter.com/rubydwarf。
アップデートをお楽しみに。 HasuraバックエンドをVueJSフロントエンドに接続する方法についてのブログポストをもう1つ公開します🎉
コミュニティーに参加しよう
Hasuraは、ますます多くの開発者によって使用されています。 フレンドリーなコミュニティに参加して、最新情報を入手してください。
あなたがHasuraであなた自身のプロジェクトを作り始めたいなら、このリンクからdiscordのチャンネルに参加することができます：https://discordapp.com/invite/hasura
すでにかなり大きなコミュニティがあり、あなたはすぐに助けを得るでしょう。
🐦Twitter：https://twitter.com/hasurahq