使う
アプリの登録と運用
検証用の利用環境で、アプリを1つ登録し、データを操作し、止めて再開するまでを通しで行う手順です。既存の顧客データには、そのまま適用しないでください。
先に、利用者として接続すると、HTTP・実行例を確認してください。
登場人物
この手順には、次の人と処理が登場します。用語は用語集にもあります。
| 登場するもの | この手順での役割 | 必要な権限 |
|---|---|---|
| 利用者 | 基盤にログインして、アプリのデータを作成・更新・削除する人 | 対象の表の読み取り・書き込み・削除の範囲 |
| 組織の管理者 | あなたの組織で、利用者に表を使う権限を与え、アプリ定義を登録し、serviceを承認する人 | 管理権限（manage_accessとservice_administratorの両方）と、MFA |
| 表の設計者 | アプリの表の設計を担う人。表の設計の権限を、持つ必要がある | 対象の表のcan_design |
| あなた（開発者） | 手順を実行し、アプリを登録して、結果を確認する | 手順ごとの実施者の権限 |
| service | 人の操作を介さずに動く処理。最後に設定する | 組織の管理者の承認 |
管理権限について
管理権限（manage_accessとservice_administrator）は、利用環境で事前に登録された権限です。誰が初期設定を行うかは、利用環境の取り決めによります。表の権限のroleとして、付与することはできません。自分で権限を上げるAPIもありません。
GET /v1/meのpermissionsとcapabilitiesには、これらが出るとは限りません。持っているかどうかを、自分で確かめる方法は、現在ありません。権限の付与は、環境管理者に依頼してください。権限がないのに、管理のAPIへ試しに書き込む方法で、確認しないでください。
全体の流れ
| 手順 | 実施者 | 目的 |
|---|---|---|
| 1. 利用者に権限を与える | 組織の管理者 | 利用者が、表を使えるようにする |
| 2. アプリを計画して登録する | 組織の管理者（対象の表のcan_designも必要） | アプリが使う表と依存先を、基盤に登録する |
| 3. データを作成・取得・更新する | 利用者 | 登録した表を、利用者の権限で使う |
| 4. 関連を設定する | 表の設計者（can_designを持つ利用者） | 表どうしの親子の関係を設定する |
| 5. 削除と復元 | 利用者 | 行を削除し、ごみ箱から戻す |
| 6. 停止と再開 | 組織の管理者 | アプリを止め、再開する |
| 7. serviceを設定する | 組織の管理者と開発者 | 人の操作を介さない処理に、限られた権限を与える |
| 8. 記録して終了する | あなた | 結果を記録する |
1. 利用者に権限を与える
実施者: 組織の管理者
アプリのデータを使う利用者に、対象の表を使う権限を与えます。権限は、表ごと、利用者ごとに設定します。
GET /v2/access/subjectsで利用者の一覧を、GET /v2/access/tablesで表の一覧を確認します。GET /v2/access/grants/{subjectId}/{collection}で、現在の権限とversionを取得します。PUTで、最新のversion、enabled、role、read_scope、write_scope、can_design、can_close、can_import、expires_atを送ります。
- 初回の
version=0は、現在の権限がないことを取得して確認した場合だけ使います。 expires_atは、実施する時点より未来の、承認の期限にします。- 権限の変更では、
Idempotency-KeyとIf-Matchを使いません。本文のversionを使います。 - 削除の範囲は、別の契約です。
write_scopeだけで削除できるとは限りません。削除の範囲（none・own・all）は、GET /v2/access/deletions/{subjectId}/{collection}で確かめ、同じパスのPUTで設定します（利用環境で有効な場合）。このPUTは、上の権限の変更と違い、本文のversion・scope・expires_at・reasonに加えて、ヘッダーのIdempotency-Keyが必要です。利用者の今の削除の範囲は、表の定義の応答のdelete_scopeで確かめられます。 - 設定した後、利用者の新しいリクエストで、許可と拒否を確認します。
- まだ作っていない表の識別子にも、期限付きの権限を設定できます。先に、表の設計の権限（
can_design）を付けてから、アプリを計画して登録します。権限を設定する相手の利用者は、登録済みである必要があります。 roleは、^[a-z][a-z0-9_-]{0,47}$の名前です。ownerは予約されていて、使えません。roleの名前は、列のread・writeと、表のexport_rolesにある、同じ名前と照合されます。列のwriteは、readに含まれる必要があります。GET /v2/access/subjectsは、id、active、actor_typeだけを返し、表示名は返しません。どのidが誰かは、環境管理者から受け取る対応表などで、確認します。
2. アプリを計画して登録する
実施者: 組織の管理者。登録する表については、実施する利用者に、can_design（表の設計の権限）が必要です。
登録の前に「計画」を作り、変更の内容を確認してから、同じ内容で「適用」します。
POST /v2/apps/planに、id、version、name、datasets、dependenciesを持つmanifestを送ります。ownedはアプリが所有する表、sharedは既存の共有表です。新しい表を作るにも、事前に設計の権限が必要です。- 返った
changesを確認します。 - 同じmanifestと、返された
fingerprintで、POST /v2/apps/applyを実行します。Idempotency-Keyが必須です。例にあるaaaa…のfingerprintを、実際には送らないでください。 GET /v2/apps/{appId}と、各表のdefinitionで、登録の結果を確認します。
manifestのversionは、新しいアプリでは1、更新では、現在の版に1を足した値です。更新するときは、現在の状態を読み、更新したmanifestで計画を作り、同じmanifestとfingerprintで適用します。競合したときは、計画を取り直して、差分を確認します。revisionは、停止・再開などの状態の変更を含めた、競合を防ぐための版です。manifest.versionとは別の値で、揃える必要はありません。停止と再開では、取得したrevisionを、そのまま送ります。
計画と適用の間に前提が変わったときは、競合として、再計画と再確認を行います。アプリの登録は、画面のプログラムのアップロードや、サーバーへの配置を行いません。
3. データを作成・取得・更新する
実施者: 利用者
ここからは、利用者の資格で操作します。
- definitionの
schema_versionと、書ける列を確認します。 POST /v2/tables/{collection}/batchのcreateにvaluesを送ります。idと所有者は、基盤が決めます。返ったidとversionを保存します。- 検索（
query）で取得します。 updateには、保存したidとversionを指定します。
作成と更新は、別のIdempotency-Keyを使います。412が返ったときは、競合・再送・復帰に従い、再取得、比較、利用者への確認へ進みます。結果が不明なだけのときは、同じキーと本文を保持します。
4. 関連を設定する
実施者: 表の設計者（can_designを持つ利用者）
子の表に、関連用の列を定義します。親と子の関係を、基盤に伝えます。
PUT /v2/tables/{collection}/accessに、mode、parent_collection、field、cardinalityを送ります。If-Matchには関連設定の現在のversionを、Idempotency-Keyも指定します。- 親に所属する方式では、親と子の、現在の権限を確認します。
- 複数の表を一括で変更する
POST /v2/transactionsは、最大8表、合計100行の操作です。既存の親のidを使い、各表のschema_versionを指定します。
5. 削除と復元
実施者: 利用者
- ごみ箱の保持期間が設定されていることと、利用者の削除の範囲を、先に確認します。
deleteに、行のidとversion、必要ならreasonを送ります。GET /v2/tables/{collection}/trashで、trash_idと現在のversionを取得します。POST /v2/tables/{collection}/trash/{trashId}/restoreに、そのversion、reason、Idempotency-Keyを渡します。
rowIdとtrashIdを取り違えないでください。定義の変更、期限切れ、現在の権限による拒否は、自動では回避しません。
6. 停止と再開
実施者: 組織の管理者
停止と再開は、行の操作とは別の、アプリの状態の操作です。
GET /v2/apps/{appId}で、revisionを取得します。POST /v2/apps/{appId}/stateに、Idempotency-Keyを付けて、action=stop、revision、reasonを送ります。- 再開は、別の
Idempotency-Keyと、現在のrevisionで、action=resumeを送ります。停止と再開の、どちらもreasonが必須です。
trash、restore、detachも同じ状態のAPIですが、保持期間、依存先、現在の状態に従います。復元した直後はstoppedになります。必要な確認の後に、明示的に再開します。
7. serviceを設定する
実施者: 組織の管理者と開発者
serviceとして接続するの手順で、申請、承認、provision、private_key_jwt、activateを行います。
確認すること:
- serviceの検索（query）が成功する。
- 許可されていない列、表、操作が、拒否される。
- 人向けの
GET /v1/meが、拒否される。 - 書き込みを許可するときは、serviceのbatch（最大50操作）を使い、本文の現在の版と
Idempotency-Keyを確認する。 - suspendまたはrevokeの後に、古い資格が拒否される。
8. 記録して終了する
対象のAPI版、利用環境、実施した時刻、操作ID、HTTPとcodeとrequest_id、許可と拒否、再試行したときの同じ操作の識別子を記録します。資格と原本のデータは、記録しません。