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の加工

• beforeRead

• beforeReadMany

• beforeDelete

• beforeDeleteMany

• beforeUpdateQuery

• beforeNewtQuery

• beforeMongoQuery

作成・更新データの加工

• beforeEffect
• beforeCreate
• beforeUpdate

レスポンスの加工

• afterCreate
• afterRead
• afterReadEach
• afterReadMany
• afterUpdate
• afterDelete
• afterDeleteMany

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した結果のデータ件数が３件だった場合は３回コールされます。

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 // 編集したレスポンスボディを返却します。
}