API処理の拡張
はじめに
ここではCollectionConfig
を使ってAPIの機能を拡張する方法を説明します。
認証、や権限、データの加工や、データの付与などさまざまな拡張を行えます。
Access
AccessはAPIへのアクセスをコントロールします。
CollectionConfig
のaccess
を設定します。
/**
* Access control
*/
access?: {
create?: Access;
read?: Access;
readMany?: Access;
dataProvider?: Access;
update?: Access;
delete?: Access;
deleteMany?: Access;
};
export type Access = (req: any, user?: any) => Promise<boolean> | boolean;
accessではAPIへのアクセスを許可・拒否を行います。 以下は簡単な例です。
access: {
create: (req, user)=>{
if(user.roleId !== "Admin"){
return true;
}
return false;
}
}
この例ではPOSTメソッドをアドミン以外は利用できなくするサンプルです。
デフォルトではfalse
が変えるようになってます。従ってAPIを有効にしたい場合はtrue
を返却する関数を渡す必要があります。
Validation
リクエストのバリデーションを行うにはCollectionConfig
で以下の設定を行います。
/**
* Validation
*/
validate?: {
create?: Validate;
read?: Validate;
readMany?: Validate;
dataProvider?: Validate;
update?: Validate;
delete?: Validate;
deleteMany?: Validate;
unlock?: Validate;
};
各フィールド、create
,read
,readMany
...には関数を記述します。
第一引数req
にExpressのリクエストが渡されます。例えばreq.body
でリクエストボディが取得できます。
export type Validate = (req: any, user: any) => any;
簡単な例
validate: {
create: (req, user)=>{
if(!req.body.id){
return {
status: "error",
message: `id is required.`,
};
}
}
}
このように、エラーならオブジェクトを返却します。APIのレスポンスとしてその値が返却されます。 エラーがない場合は戻り値なしとしてください。
Authorization
簡単なサンプル。データの作成を認証必須にします。 データの作成は認証されたユーザのみ、データの読み込みは誰でもできるという設定をする場合、以下のようになります。
authorization: {
create: () => true,
read: () => false
}
createのAPIで、true
を関数で返却すれば認証が必須になります。
認証はAPIキー
を使用し、nAuthで行われます。
Callbacks
Callbacksは、コレクションの機能を拡張し、自分のロジックを実行するための強力な方法であり、コレクションごとに定義することができます。詳細については、フックのドキュメントをご覧ください。
各種APIの処理はカスタマイズできます。 カスタマイズすることで、特定の条件でのみ処理を許可したり、データの読み書き以外の処理を合わせて行うことができます。
例えば、お問合せを受け付けてメールを送信するAPI、注文を受け付けたら決済処理を行うAPIなど。
コールバック関数によって以下のような事ができます。
callbackに指定できる関数は以下の通りです。
Queryの加工
作成・更新データの加工
レスポンスの加工
Configration
Callbacksを使うためにはCollectionConfig
に設定します。
各コールバックは専用の引数が与えられます。
import { CollectionConfig } from "newtzero-sdk";
const ItemConfig: CollectionConfig = {
collectionName: "item",
//...省略
callbacks: {
beforeCreate(req, user, data) {
data.create_date = new Date();
return date;
}
//...another callbacks...
}
};
export default ItemConfig;
beforeRead
データの読込前に、呼び出されます。この関数はデータを読み出す前にQueryを編集します。
読み込む条件として特別な条件を追加したい場合に役立ちます。
const beforeRead = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
query, // MongoDBに実行予定のクエリ
id //URLに指定された取得したいデータのID
}) => {
//処理を行ないます。
return query // 編集したクエリを返却します。
}
beforeReadMany
データの読込前に、呼び出されます。この関数はデータを読み出す前にQueryを編集します。
読み込む条件として特別な条件を追加したい場合に役立ちます。
const beforeReadMany = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
query // MongoDBに実行予定のクエリ
}) => {
//処理を行ないます。
return query // 編集したクエリを返却します。
}
beforeDelete
データを削除する直前に呼び出されます。この関数はデータを削除する前にQueryを編集します。
削除するデータの条件として特別な条件を追加したい場合に役立ちます。
const beforeDelete = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
query, // MongoDBに実行予定のクエリ
id //URLに指定された削除したいデータのID
}) => {
//処理を行ないます。
return query // 編集したクエリを返却します。
}
beforeDeleteMany
データを削除する直前に呼び出されます。この関数はデータを削除する前にQueryを編集します。
削除するデータの条件として特別な条件を追加したい場合に役立ちます。
const beforeDeleteMany = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
query // MongoDBに実行予定のクエリ
}) => {
//処理を行ないます。
return query // 編集したクエリを返却します。
}
beforeUpdateQuery
データを更新する直前に呼び出されます。この関数はデータを更新する前にQueryを編集します。
更新するデータの条件として特別な条件を追加したい場合に役立ちます。
const beforeUpdateQuery = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
query // MongoDBに実行予定のクエリ
}) => {
//処理を行ないます。
return query // 編集したクエリを返却します。
}
beforeNewtQuery
DataProvider APIをリクエストする際にQueryが実行される前に呼び出されます。callback関数によってNewtQueryを加工し、データを読み込みます。 callbackに渡される引数は以下の通りです。
const beforeNewtQuery = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
newtQuery: NewtQuery, // newtQueryが入ります。
orderQ?: any, //newtQueryのorder部分だけが入ります。
searchQ?: any, //newtQueryのsearch部分だけが入ります。
matchQ?: any, //newtQueryのmatch部分だけが入ります。
limit?: number, //newtQueryのlimit部分だけが入ります。
skip?: number //newtQueryのskip部分だけが入ります。
}) => {
//処理を行ないます。
return newtQuery // 編集したnewtQueryを返却します。
}
引数 | 型 | 説明 |
---|---|---|
req | Request | リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。 |
user | User | APIリクエストしたユーザーです。 |
newtQuery | NewtQuery or undefined | |
orderQ | newtQueryのorder部分 | |
limitQ | newtQueryのlimit部分 | |
skipQ | newtQueryのskip部分 | |
searchQ | newtQueryのsearch部分 | |
matchQ | newtQueryのmatch部分 |
戻り値 | 型 | 説明 |
---|---|---|
newtQuery | NewtQuery | 加工したNewtQueryを返却します。 |
beforeMongoQuery
NewtQueryから変換されたMongoQueryが実行される前に呼び出されます。 callback関数によってMongoQueryを加工し、データを読み込みます。NewtQueryでは行えないような複雑なクエリ条件を付与したい場合はこちらでqueryの加工をしてください。
callbackに渡される引数・戻り値は以下の通りです。
const beforeMongoQuery = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
query // MongoDBに実行予定のクエリ
}) => {
//処理を行ないます。
return query // 編集したMongoクエリを返却します。
}
beforeEffect
NewtZeroConfigのpluginが呼ばれる直前に呼び出されます。 callbackに渡される引数・戻り値は以下の通りです。
const beforeEffect = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
data // 保存・更新予定のデータ
}) => {
//処理を行ないます。
return data // 編集したdataを返却します。
}
beforeCreate
データをセーブする直前に呼び出されます。callback関数によってデータを加工し、データベースへ保存します。 callbackに渡される引数は以下の通りです。
const beforeCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
data // 保存・更新予定のデータ
}) => {
//処理を行ないます。
return data // 編集したdataを返却します。
}
beforeUpdate
データをセーブする直前に呼び出されます。callback関数によってデータを加工し、データベースへ保存します。 callbackに渡される引数は以下の通りです。
const beforeCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
data // 保存・更新予定のデータ
}) => {
//処理を行ないます。
return data // 編集したdataを返却します。
}
afterReadEach
このコールバック関数はレスポンスを返却する前に呼び出されます。 レスポンスデータを受け取り、加工し返却をします。 レスポンスデータの形式やデータの加工を行いたい場合に有効です。 引数にデータが一件毎渡されます。 データを加工して返却します。readManyもしくはdataProviderでのみ呼び出されます。 例えば、readした結果のデータ件数が3件だった場合は3回コールされます。
const afterReadEach = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
data // データ 配列データ一件毎にこのコールバックが呼び出されます。dataには一件のデータのみが入ります。
}) => {
//処理を行ないます。
return query // 編集したMongoクエリを返却します。
}
afterCreate
このコールバック関数はレスポンスを返却する前に呼び出されます。 レスポンスデータを受け取り、加工し返却をします。 レスポンスデータの形式やデータの加工を行いたい場合に有効です。
const afterCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
resBody // APIのレスポンスとして返却するデータ全体
}) => {
//処理を行ないます。
return resBody // 編集したレスポンスボディを返却します。
}
afterRead
このコールバック関数はレスポンスを返却する前に呼び出されます。 レスポンスデータを受け取り、加工し返却をします。 レスポンスデータの形式やデータの加工を行いたい場合に有効です。
const afterCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
resBody // APIのレスポンスとして返却するデータ全体
}) => {
//処理を行ないます。
return resBody // 編集したレスポンスボディを返却します。
}
afterReadMany
このコールバック関数はレスポンスを返却する前に呼び出されます。 レスポンスデータを受け取り、加工し返却をします。 レスポンスデータの形式やデータの加工を行いたい場合に有効です。
const afterCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
resBody // APIのレスポンスとして返却するデータ全体
}) => {
//処理を行ないます。
return resBody // 編集したレスポンスボディを返却します。
}
afterUpdate
このコールバック関数はレスポンスを返却する前に呼び出されます。 レスポンスデータを受け取り、加工し返却をします。 レスポンスデータの形式やデータの加工を行いたい場合に有効です。
const afterCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
resBody // APIのレスポンスとして返却するデータ全体
}) => {
//処理を行ないます。
return resBody // 編集したレスポンスボディを返却します。
}
afterDelete
このコールバック関数はレスポンスを返却する前に呼び出されます。 レスポンスデータを受け取り、加工し返却をします。 レスポンスデータの形式やデータの加工を行いたい場合に有効です。
const afterCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
resBody // APIのレスポンスとして返却するデータ全体
}) => {
//処理を行ないます。
return resBody // 編集したレスポンスボディを返却します。
}
afterDeleteMany
このコールバック関数はレスポンスを返却する前に呼び出されます。 レスポンスデータを受け取り、加工し返却をします。 レスポンスデータの形式やデータの加工を行いたい場合に有効です。
const afterCreate = async({
req, //expressのリクエストオブジェクト
user, //認証した場合、ユーザ情報が入ります。
resBody // APIのレスポンスとして返却するデータ全体
}) => {
//処理を行ないます。
return resBody // 編集したレスポンスボディを返却します。
}