mirror of
https://github.com/kou029w/hasura-rest-hands-on.git
synced 2025-01-18 16:08:14 +00:00
書いた
This commit is contained in:
parent
3d7a6489c0
commit
f0d9beef01
11 changed files with 263 additions and 38 deletions
|
|
@ -1,8 +1,29 @@
|
|||
# Hasuraで作るREST API
|
||||
|
||||
Hasuraを使用してPostgresデータベースに接続したREST APIを構築します。
|
||||
Hasuraを使用してPostgresデータベースに接続したREST APIを構築し、それを利用したWebアプリを作成します。
|
||||
|
||||
<!-- TODO:
|
||||
これから作成する構成 - Heroku Database/Hasura Cloud/CodeSandbox/Vue 3/Quill)
|
||||
https://qfmmc.csb.app/
|
||||
-->
|
||||
これからこのハンズオンで作成するのは次のようなWebアプリです。
|
||||
|
||||
<!-- TODO: 自由に編集できてしまうので削除するか修正して -->
|
||||
<iframe
|
||||
src="https://codesandbox.io/embed/vue3-hasura-rest-qfmmc?fontsize=14&hidenavigation=1&view=preview"
|
||||
style="
|
||||
width: 100%;
|
||||
height: 500px;
|
||||
border: 0;
|
||||
border-radius: 4px;
|
||||
overflow: hidden;
|
||||
"
|
||||
title="vue3-hasura-rest"
|
||||
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
|
||||
></iframe>
|
||||
|
||||
構成としては下記の通りです。
|
||||
|
||||
- [Hasura Cloud](https://cloud.hasura.io/) - すぐに利用可能なHasuraの環境
|
||||
- [Heroku Postgres](https://jp.heroku.com/postgres) - すぐに利用可能なデータベース
|
||||
- [CodeSandbox](https://codesandbox.io/) - フロントエンドのオンライン開発環境
|
||||
- [Vue 3](https://v3.vuejs.org/) - プログレッシブWebフレームワーク
|
||||
- [Quill](https://quilljs.com/) - リッチテキストエディター
|
||||
|
||||
それではさっそく作っていきましょう!
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
- [Herokuのアカウント登録](signup-heroku.md)
|
||||
- [Hasura Cloudのアカウント登録](signup-hasura-cloud.md)
|
||||
- [Hasura Cloudプロジェクトの作成](create-project.md)
|
||||
- [Heroku Databaseへの接続](create-heroku-database.md)
|
||||
- [Heroku Postgresへの接続](create-heroku-postgres.md)
|
||||
- [テーブルの作成](create-table.md)
|
||||
- [GraphQLによるデータの挿入と取得](insert-and-select.md)
|
||||
- [REST APIエンドポイントの作成](create-rest-endpoint.md)
|
||||
|
|
|
|||
|
|
@ -1,11 +0,0 @@
|
|||
# Heroku Databaseへの接続
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
31
docs/create-heroku-postgres.md
Normal file
31
docs/create-heroku-postgres.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# Heroku Postgresへの接続
|
||||
|
||||
Hasuraでデータの保存と検索を実現するためにデータベースを接続します。
|
||||
|
||||
このハンズオンでは、データベースとしてHeroku Postgresを利用します。
|
||||
|
||||
Hasura Cloudのプロジェクトの[Launch Console]ボタンからHasuraのコンソール画面にアクセスして、Heroku Postgresへの接続を行うことが可能です。
|
||||
|
||||
まず、コンソール > [Data Manager] にアクセスします。
|
||||
|
||||
|
||||
|
||||
[Create Heroku Database]を選択し、データベース作成パネルを表示します。
|
||||
|
||||
|
||||
|
||||
[Create Database]ボタンを選択し、Heroku Postgresデータベースを新たに作成します。Herokuとの連携を行う際に、初回アクセス時にはHerokuの承認画面が表示されます。[Allow (許諾)]を選択するとHerokuとの連携が完了します。
|
||||
|
||||
|
||||
|
||||
一連の手順でHeroku Postgresデータベースを作成すると、Hasuraは自動的にデータベースへの接続を開始します。
|
||||
|
||||
|
||||
|
||||
しばらく待つと、データベースへの接続が完了します。
|
||||
|
||||
これであなたはHasuraを利用可能になりました 🎉
|
||||
|
||||
|
||||
|
||||
それでは実際にHasuraを使ってみましょう!
|
||||
|
|
@ -1,12 +1,32 @@
|
|||
# Hasura Cloudプロジェクトの作成
|
||||
|
||||
もし、プロジェクトが存在しない場合、まずプロジェクトの作成を行います。
|
||||
すでに存在するプロジェクトを利用する場合は不要です。
|
||||
Hasuraを利用するためにHasura Cloudのプロジェクトを作成します。
|
||||
|
||||
プロジェクトが存在しない場合、まずプロジェクトの作成を行います。
|
||||
すでに存在するプロジェクトを利用する場合は、下記のプロジェクトの作成の作業は不要です。
|
||||
|
||||
## プロジェクトの作成
|
||||
|
||||
[Hasura Cloudのトップページ](https://cloud.hasura.io/)にアクセスすると、プロジェクトの一覧画面が表示され、[Create Project]ボタンから、プロジェクト作成フォームを開きます。
|
||||
|
||||
プロジェクト作成フォームに必要事項を入力します。ここでは例として次の項目を入力します。
|
||||
|
||||
| 項目 | 説明 | 例 |
|
||||
| --------------------- | --------------------- | ---------------------------------------------------------------- |
|
||||
| Choose a pricing plan | 料金プランの選択 | Free Tier - 無料 |
|
||||
| Select a region | リージョン | US West (N. California) - 無料で利用可能なデフォルトのリージョン |
|
||||
| Enter a project name | プロジェクト名 (任意) | `memo-demo` |
|
||||
|
||||
必要事項を入力後、[Create project]ボタンを押し、プロジェクトを作成します。
|
||||
|
||||
|
||||
|
||||
プロジェクトの作成が完了すると、画面上にプロジェクトの詳細が表示されます。
|
||||
|
||||
|
||||
|
||||
画面上にプロジェクトが表示されれば完了です。
|
||||
|
||||
|
||||
|
||||
画面上にプロジェクトが表示されれば完了です。
|
||||
プロジェクトの[Launch Console]ボタンからHasuraのコンソール画面にアクセスして、Heroku Postgresへの接続を行いましょう。
|
||||
|
|
|
|||
|
|
@ -1,9 +1,23 @@
|
|||
# REST APIエンドポイントの作成
|
||||
|
||||
|
||||
ここまでは、GraphQLを使った操作を試しました。この時点でリクエストヘッダーに秘密鍵を与えれば、実際にGraphQL APIエンドポイントを利用することが可能です。
|
||||
|
||||
get page
|
||||
GET page/:id
|
||||
このハンズオンでは最後にREST APIエンドポイントを作成し、WebアプリケーションからGraphQL APIではなくREST APIを利用します。ここからはそのための手順を説明します。
|
||||
|
||||
## 設計
|
||||
|
||||
Hasuraは、GraphQL QueryをREST化することが可能です。このハンズオンでは、次の仕様のREST APIエンドポイントを作成します。
|
||||
|
||||
| 名称 | HTTPメソッドとパス | 説明 |
|
||||
| ------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| ページの取得 | `GET /api/rest/page/:id` | 割り当てられた識別子 `id` をもつページを取得します。レスポンスボディには `data.page.content` プロパティを含みます。 |
|
||||
| ページの更新 | `PUT /api/rest/page/:id` | 割り当てられた識別子 `id` をもつページを更新します。リクエストボディには `content` プロパティを与えます。 |
|
||||
|
||||
## 「ページの取得 (`GET page/:id`)」エンドポイントの作成
|
||||
|
||||
ページを取得するためのREST APIエンドポイントを作成します。
|
||||
|
||||
コンソールのトップ画面のGraphiQLのパネルにアクセスし、次のコードを書きます。
|
||||
|
||||
```graphql
|
||||
query getPage($id: Int!) {
|
||||
|
|
@ -14,12 +28,23 @@ query getPage($id: Int!) {
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
[REST]ボタンを選択し、REST APIエンドポイント作成フォームを表示します。次の必要事項を入力し、作成ボタンを選択しエンドポイントを作成します。
|
||||
|
||||
| 項目 | 説明 | 内容 |
|
||||
| -------- | ----------------------- | ---------- |
|
||||
| Name | エンドポイントの名称 | get page |
|
||||
| Location | `/api/rest/` 以降のパス | `page/:id` |
|
||||
| Method | HTTPメソッド | `GET` |
|
||||
|
||||
|
||||
|
||||
|
||||
## 「ページの更新 (`PUT page/:id`)」エンドポイントの作成
|
||||
|
||||
put page
|
||||
PUT page/:id
|
||||
ページを更新するためのREST APIエンドポイントを作成します。
|
||||
|
||||
コンソールのトップ画面のGraphiQLのパネルにアクセスし、次のコードを書きます。
|
||||
|
||||
```graphql
|
||||
mutation putPage($id: Int!, $content: jsonb!) {
|
||||
|
|
@ -33,4 +58,16 @@ mutation putPage($id: Int!, $content: jsonb!) {
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
[REST]ボタンを選択し、REST APIエンドポイント作成フォームを表示します。次の必要事項を入力し、作成ボタンを選択しエンドポイントを作成します。
|
||||
|
||||
| 項目 | 説明 | 内容 |
|
||||
| -------- | ----------------------- | ---------- |
|
||||
| Name | エンドポイントの名称 | put page |
|
||||
| Location | `/api/rest/` 以降のパス | `page/:id` |
|
||||
| Method | HTTPメソッド | `PUT` |
|
||||
|
||||
|
||||
|
||||
作成すると作成したREST APIエンドポイントが表示されます。
|
||||
|
|
|
|||
|
|
@ -1,12 +1,24 @@
|
|||
# テーブルの作成
|
||||
|
||||
[Data Manager] > [View Database] > [Add a new table]を選択し、新しいテーブルを作成します。
|
||||
|
||||
このハンズオンでは、次のデータモデルを作成します。
|
||||
|
||||
テーブル名: `pages` - メモ帳のページ
|
||||
|
||||
| 項目 | 型 | 説明 |
|
||||
| --------- | ------------------------ | ----------------------------------------------------------------------------------- |
|
||||
| `id` \* | Integer (auto-increment) | ページの識別子 |
|
||||
| `content` | JSONB | ページの本文 ([Quill Deltaオブジェクト](https://quilljs.com/docs/delta/)を使う想定) |
|
||||
|
||||
\*: Primary Key
|
||||
|
||||
データモデルのための必要事項を入力し、テーブルを作成します。Primary Keyとして `id` (ページの識別子)を選択します。
|
||||
|
||||
|
||||
|
||||
<!--
|
||||
TODO: テーブル
|
||||
pages
|
||||
id int autoincrement
|
||||
content jsonb
|
||||
-->
|
||||
テーブルの作成が完了するとその作成したテーブルの[Modify]パネルが表示されます。作成したテーブルへの変更はHasuraによって自動的に追従されます。
|
||||
|
||||
|
||||
|
||||
これでHasuraからGraphQLによるデータへの操作が可能になります。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,17 @@
|
|||
# Vueアプリケーションの作成
|
||||
|
||||
https://qfmmc.csb.app/
|
||||
[](https://codesandbox.io/s/vue3-hasura-rest-qfmmc?file=/src/App.vue)
|
||||
|
||||
このリンクからCodeSandboxにアクセスし、Vueアプリケーションを作成します。
|
||||
|
||||
<!-- TODO:
|
||||
編集用に配置して
|
||||
[](https://codesandbox.io/s/github/kou029w/hasura-rest-hands-on/tree/master/frontend)
|
||||
-->
|
||||
|
||||
<!-- TODO: /frontend にあるコードを埋め込んで -->
|
||||
|
||||
なお、URLに含まれる `memo-demo` は、Hasura Cloudプロジェクト名によって異なるので、適宜自分の作成したプロジェクトに合わせて読み替えてください。
|
||||
|
||||
```vue
|
||||
<template>
|
||||
|
|
@ -44,4 +55,10 @@ export default {
|
|||
|
||||
|
||||
|
||||
Hasuraのコンソールにアクセスすると、実際にデータが更新されていることを確認することが可能です。
|
||||
|
||||
|
||||
|
||||
Hasuraを使用してPostgresデータベースに接続したREST APIを構築し、それを利用したWebアプリを作成しました。いかがでしたか。
|
||||
|
||||
このハンズオンは以上です。もし質問や提案、問題などあれば[GitHub Issues](https://github.com/kou029w/hasura-rest-hands-on/issues/new)にてお気軽にご報告ください。
|
||||
|
|
|
|||
|
|
@ -1,9 +1,18 @@
|
|||
# GraphQLによるデータの挿入と取得
|
||||
|
||||
<!--
|
||||
TODO:
|
||||
(GraphQLの基本)
|
||||
-->
|
||||
HasuraからGraphQLによるデータへの操作を行ってみましょう。
|
||||
|
||||
コンソールのトップ画面に戻ると、GraphiQL (GraphQLのプレイグラウンド、開発環境) を使ってGraphQL APIを実際に試すことが可能です。
|
||||
|
||||
## データの挿入
|
||||
|
||||
まずGraphQLでデータの挿入を試します。ここでは例として `pages` テーブルに次のデータを書き込みます。
|
||||
|
||||
| 項目 | 説明 | 値 |
|
||||
| --------- | ------------ | ----------------------- |
|
||||
| `content` | ページの本文 | `{}` - 空のオブジェクト |
|
||||
|
||||
GraphQL Queryとしては次のコードを書いて、▶ ボタンからリクエストを行います。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```graphql
|
||||
|
|
@ -16,8 +25,18 @@ mutation MyMutation {
|
|||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
サーバーにリクエストを発行しレスポンスボディとして得られたデータは、右側のパネルに表示されます。
|
||||
|
||||
|
||||
|
||||
問題無くJSONのデータが得られたら、別のデータの書き込みを試してみます。
|
||||
|
||||
例として `pages` テーブルに次のデータを書き込みます。
|
||||
|
||||
| 項目 | 説明 | 値 |
|
||||
| --------- | ------------ | ---------------- |
|
||||
| `content` | ページの本文 | `{hey: "hello"}` |
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```graphql
|
||||
mutation MyMutation {
|
||||
|
|
@ -29,10 +48,22 @@ mutation MyMutation {
|
|||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
レスポンスを見ると問題なく `id` (ページの識別子) が得られており、正しく割り当てられ、テーブル内に書き込まれているようですね。
|
||||
|
||||
|
||||
|
||||
実際にデータベースのテーブルに書き込まれていることを確認してみます。[Data Manager] > [View Database] > `pages` テーブルを選択すると[Browse Rows]パネルでテーブル内のデータを確認することが可能です。
|
||||
|
||||
先ほどのGraphQL Queryリクエストが問題なく発行され、正しくデータが書き込まれていますね。
|
||||
|
||||
|
||||
|
||||
## データの取得
|
||||
|
||||
上述の `pages` テーブル内からGraphQLでデータの取得を試します。取得するために、データに割り当てられた `id` を使います。
|
||||
|
||||
GraphQL Queryとしては次のコードを書いて、▶ ボタンからリクエストを行います。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```graphql
|
||||
query MyQuery {
|
||||
|
|
@ -44,4 +75,15 @@ query MyQuery {
|
|||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
レスポンスを見ると、問題なく先ほど書き込まれたのテーブル内データが得られていますね。
|
||||
|
||||
| 項目 | 説明 | 例 |
|
||||
| --------- | -------------- | ---------------- |
|
||||
| `id` | ページの識別子 | `2` |
|
||||
| `content` | ページの本文 | `{hey: "hello"}` |
|
||||
|
||||
|
||||
|
||||
GraphQLでデータの挿入と取得を実際に試してみて、いかがでしたか。
|
||||
|
||||
このハンズオンではGraphQLの具体的なオペレーション `mutation` や `query`、Hasuraの提供しているデータのCRUDのためのフィールド `insert_*` や `*_by_pk` について詳しくは説明しません。しかし実際にはここで紹介した以外にもさまざまな操作を行うことが可能です。[Explorer]のパネルから実行可能な操作や型、あるいは右側の[< Docs]等からGraphQLの型の詳細を参照してみると、実際の操作の参考になるかと思います。
|
||||
|
|
|
|||
|
|
@ -1,17 +1,71 @@
|
|||
# アクセス権の設定
|
||||
|
||||
アクセス権の設定を行います。Hasuraはテーブルの行単位でアクセス制御を行うことが可能です。このハンズオンでは秘密鍵を持たずとも誰でもREST APIを利用できるようにします。
|
||||
|
||||
**注: セキュアではないので本番環境ではJWK等で認証しましょう**
|
||||
|
||||
[Data Manager] > [View Database] > `pages` テーブル > [Permissions]パネルから、テーブル内のデータのアクセス件を設定可能です。
|
||||
|
||||
認証・認可していない利用者のために、ここでは例として `anonymous` ロールを割り当てます。
|
||||
|
||||
|
||||
|
||||
## insert (データの挿入) 権限の設定
|
||||
|
||||
`anonymous` ロールの行 > insert の列を選択し、データの挿入の権限の設定を行います。
|
||||
|
||||
下記の項目を選択し、[Save Permissions]ボタンで権限を保存します。
|
||||
|
||||
- Row insert permissions > Without any checks
|
||||
- Column insert permissions > `id` `content` ([Toggle All]ボタンを押す)
|
||||
|
||||
|
||||
|
||||
## select (データの取得) 権限の設定
|
||||
|
||||
`anonymous` ロールの行 > select の列を選択し、データの取得の権限の設定を行います。
|
||||
|
||||
下記の項目を選択し、[Save Permissions]ボタンで権限を保存します。
|
||||
|
||||
- Row select permissions > Without any checks
|
||||
- Column select permissions > `id` `content` ([Toggle All]ボタンを押す)
|
||||
|
||||
|
||||
|
||||
## update (データの更新) 権限の設定
|
||||
|
||||
`anonymous` ロールの行 > update の列を選択し、データの取得の権限の設定を行います。
|
||||
|
||||
下記の項目を選択し、[Save Permissions]ボタンで権限を保存します。
|
||||
|
||||
- Pre-update check > Without any checks
|
||||
- Post-update check > Without any checks
|
||||
- Column update permissions > `id` `content` ([Toggle All]ボタンを押す)
|
||||
|
||||
|
||||
|
||||
`anonymous` ロールのinsert、select、updateに✅マークが入っていれば完了です。
|
||||
|
||||
|
||||
|
||||
## 環境変数 `HASURA_GRAPHQL_UNAUTHORIZED_ROLE=anonymous` の設定
|
||||
|
||||
Hasuraの環境変数として `HASURA_GRAPHQL_UNAUTHORIZED_ROLE=anonymous` を与えることで、認証・認可していない利用者に割り当てられるロールを設定します。
|
||||
|
||||
Hasura Cloudのプロジェクトの画面に戻り、[Env vars]にアクセスします。
|
||||
|
||||
|
||||
|
||||
[+ New Env Var]ボタンを押して、環境変数を追加します。
|
||||
|
||||
| 環境変数 | 説明 | 値 |
|
||||
| ---------------------------------- | ---------------------------------------------- | ----------- |
|
||||
| `HASURA_GRAPHQL_UNAUTHORIZED_ROLE` | 認証・認可されていない利用者に割り当てるロール | `anonymous` |
|
||||
|
||||
入力後、[Add]ボタン押して追加します。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
REST APIエンドポイントをWebアプリから利用する準備が整いました 🎉
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
# 事前準備
|
||||
|
||||
あらかじめ下記のアカウントに登録しておきましょう。
|
||||
まず、事前準備としてあらかじめ下記のアカウントに登録しておきましょう。
|
||||
|
||||
- [Herokuのアカウント登録](signup-heroku.md)
|
||||
- [Hasura Cloudのアカウント登録](signup-hasura-cloud.md)
|
||||
|
||||
もし、すでにアカウント登録済みであれば、[Hasura Cloudプロジェクトの作成の章](create-project.md)まで読み飛ばしてください。
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue