APIメソッドごとの権限設定方法まとめ　Record / Record (bulk)

SPIRAL ver.2 ではグループやアプリロールを設定することで、APIエージェントに権限を付与することができます。
そしてAPIエージェントに付与された権限によって、APIを実行する場合には細かい制御ができるようになっています。
これらは SPIRAL ver.2 の１つの大きな特徴とも言えるものですが、権限をしっかり設定していないとAPIを
実行した際にエラーが発生してしまうため、初めて触った時に難しく感じる部分でもあります。

この記事では Record / Record (bulk) のメソッドごとに、どのように権限設定をすれば良いのかまとめました。
SPIRAL ver.2 でAPIを使用する時の参考になればと思います。

はじめに

権限は必要最低限で設定することで、セキュアにAPIを使用することができます。
そのためこちらの記事ではAPI実行に必要な最低限のグループ権限設定方法や、
メソッドごとのアプリロール設定をまとめています。

グループ権限設定に関して

権限を最低限にする観点からグループはAPIエージェント専用のものを作成してください。
また、 Record / Record (bulk) のAPIメソッドに関しては「利用アプリ」権限のみを設定すれば実行することが可能です。

以下の画像のように作成したグループに、API操作したいDBがあるアプリを「利用アプリ」に追加してください。

アプリロール設定に関して

アプリロールで設定できる権限は全部で６つあり、それぞれの説明を表にまとめました。

DB権限	アプリ内でAPI実行を許可するDBにだけ「あり」を設定してください。「なし」を設定したDBに対しては一切のAPI実行ができません。
レコード作成権限	APIでレコード登録する場合には「あり」に設定する必要があります。
レコード操作権限	レコードに対して「閲覧」「変更」「削除」の権限を設定することができます。条件を設定することで特定のレコードのみの操作権限を設定することも可能です。
フィールド権限	DB内で特定のフィールドに「閲覧」「作成」「変更」の権限を設定することができます。権限を設定していないフィードに対してはAPI実行ができません。
一括操作権限	APIでレコードの一括操作を実行したい場合に設定する必要があります。
メール操作権限	メール関連の権限になりますので、レコード操作系のAPIでは設定する必要がありません。

以下では、メソッドごとに権限をどのように設定すべきかまとめております。
使用するメソッドに合わせて、アプリロールを設定してください。

レコード一覧取得の設定

レコード一覧取得（【GET】apps/{app}/dbs/{db}/records ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	なし
レコード操作権限	すべてのレコードもしくは条件を絞ったレコードの「閲覧」にチェックを付けてください。
フィールド権限	必要なフィードにのみ「閲覧」のチェックを付けてください。
一括操作権限	設定不要
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

API実行の際にフィールドを指定してレコード取得をした場合、
アプリロールで指定したフィールドにチェックを付けていないとエラーとなります。
逆にフィールド指定せずにレコード取得した場合、
アプリロールでチェックが付いているフィールドのみ取得可能です。

レコード登録の設定

レコード登録（【POST】apps/{app}/dbs/{db}/records ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	あり
レコード操作権限	設定不要
フィールド権限	必要なフィードにのみ「作成」のチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
一括操作権限	設定不要
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

登録したいフィールドには、アプリロールのフィールド設定でチェックを付けてください。
チェックを付けていない場合はエラーとなります。

レコード取得の設定

レコード取得（【GET】apps/{app}/dbs/{db}/records/{recordId} ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	なし
レコード操作権限	すべてのレコードもしくは条件を絞ったレコードの「閲覧」にチェックを付けてください。
フィールド権限	必要なフィードにのみ「閲覧」のチェックを付けてください。
一括操作権限	設定不要
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

このメソッドだとフィールドを指定してレコード取得ができませんが、
アプリロールでフィールド権限を設定すればチェックがついているフィールドのみ取得可能です。
またレコード操作権限で条件を付けることで、例えばフラグが立っているレコードのみ
取得可能にするなどアプリロール側で様々な制御が可能になっています。

レコード変更の設定

レコード変更（【PATCH】apps/{app}/dbs/{db}/records ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	なし
レコード操作権限	すべてのレコードもしくは条件を絞ったレコードの「変更」にチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
フィールド権限	必要なフィードにのみ「変更」のチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
一括操作権限	設定不要
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

更新したいフィールドには、アプリロールのフィールド設定でチェックを付けてください。
チェックを付けていない場合はエラーとなります。

レコード削除の設定

レコード削除（【DELETE】apps/{app}/dbs/{db}/records ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	なし
レコード操作権限	すべてのレコードもしくは条件を絞ったレコードの「削除」にチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
フィールド権限	設定不要
一括操作権限	設定不要
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

削除メソッドは成功した場合のレスポンスがありませんのでご注意ください。

レコード検証の設定

レコード検証（【POST】apps/{app}/dbs/{db}/records/verify ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	なし
レコード操作権限	すべてのレコードもしくは条件を絞ったレコードの「閲覧」「変更」にチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
フィールド権限	レコードを識別する為の入力必須かつ重複不可のフィールドとパスワード型フィールドの「閲覧」にチェックを付けてください。
一括操作権限	設定不要
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

レコード操作権限の「変更」にチェックを付けないとエラーとなります。
ただしフィールド権限で「変更」にチェックを付けなくても大丈夫ですので、
API経由でフィールド変更がされることを防ぐことはできます。

複数レコード登録の設定

複数レコード登録（【POST】apps/{app}/dbs/{db}/records/bulk ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	あり
レコード操作権限	設定不要
フィールド権限	必要なフィードにのみ「作成」のチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
一括操作権限	「一括登録」にチェックを付けてください。
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

複数登録する場合は、一括操作権限を設定していないとエラーとなります。

複数レコード更新の設定

複数レコード更新（【PATCH】apps/{app}/dbs/{db}/records/bulk ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	なし
レコード操作権限	すべてのレコードもしくは条件を絞ったレコードの「変更」にチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
フィールド権限	必要なフィードにのみ「変更」のチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
一括操作権限	「一括更新」にチェックを付けてください。
メール操作権限	設定不要

▼ 実際の設定画面

・注意事項等

複数更新する場合は、一括操作権限を設定していないとエラーとなります。

複数レコード削除の設定

複数レコード削除（【DELETE】apps/{app}/dbs/{db}/records/bulk ）を実行したい場合には下記のようにアプリロールを設定してください。

DB権限	あり
レコード作成権限	なし
レコード操作権限	すべてのレコードもしくは条件を絞ったレコードの「削除」にチェックを付けてください。 ※仕様上「閲覧」にもチェックを付ける必要があります。
フィールド権限	設定不要
一括操作権限	「一括削除」にチェックを付けてください。
メール操作権限	設定不要