バージョン: 2.0.0

開発者用ドキュメント

NewtZero

API SDK

NewtZeroの拡張が容易になります。

利用方法

newtzeroリポジトリをクローンします。リポジトリの/nodes/newtzero/src/cms/以下にフォルダを作成し、作成したいコレクション名のフォルダを作成し直下にindex.tsを配置する。同ファイルにて、CollectionConfig型のObjectをエクスポートすることで、自動でcms用のエンドポイントが作成されます。

export type CollectionConfig = {
    projectName?:string;
    slug: string;
    metrics: MetricsCustom[];

    // Collection作成時に自動でアセットが作成されます。未指定の場合、slugの値がアセット名となります。
    assetName?: string;
    // Assetタグを指定できます。
    // デフォルトで slug:[value], assetName:[value] がタグとして付与されます。
    additionalAssetTags?: string[];


    uniqueKeys: string[];
    ttlIndexes: { key: string, expired: number }[];
    //Array of metrics names to ignore auto indexing.
    indexIgnores: string[];

    // primaryKeyを指定した場合、URLで/:idの値はprimaryKeyの値であるとみなされます。
    primaryKey: string;

    //任意のオプティマイザーロジックを設定できます。
    optimizer?: (data, metrics)=> data;

    callbacks?: {
        beforeEffect?: 
        beforeCreate?: BeforeChangeCallback;
        afterCreate?: AfterChangeCallback;
        beforeUpdate?: BeforeChangeCallback;
        afterUpdate?: AfterChangeCallback;
        beforeRead?: BeforeReadCallback;
        afterReadEach?: after
        afterRead?: AfterReadCallback;
        beforeDelete?: BeforeDeleteCallback;
        afterDelete?: AfterDeleteCallback;
        afterError?: AfterErrorCallback;
        beforeNewtQuery?: BeforeQueryCallback;
        beforeMongoQuery?: BeforeMongoQueryCallback;
    };

    authorize?: {
      create?: (req) => boolean;
      read?: (req) => boolean;
      readMany?: (req) => boolean;
      dataProvider: (req) => boolean;
      update?: (req) => boolean;
      delete?: (req) => boolean;
      unlock?: (req) => boolean;
    }
    /**
     * Access control
     */
    access?: {
        create?: Access;
        read?: Access;
        readMany?: Access;
        dataProvider: Access;
        update?: Access;
        delete?: Access;
        unlock?: Access;
    };

    validate?: {
        create?: Validate;
        read?: Validate;
        readMany?: Validate;
        dataProvider?: Validate;
        update?: Validate;
        delete?: Validate;
        unlock?: Validate;
    }

    // Customize Endpoint path
    customUrl?: {
        create?: string;
        read?: string;
        readMany?: string;
        dataProvider?: string;
        update?: string;
        delete?: string;
        unlock?: string;
    };

    // trueの場合、ドキュメント全体を与えられたオブジェクトで更新します。部分更新を防ぎ、データの一貫性を保持しやすくします。
    immutable?: boolean; //default true

    // trueの場合、データのルートが配列の場合、それぞれを個別のレコードとして保存します。
    splitArray?: boolean; // default true

};

Callback

callbackに指定できる関数は以下の通りです。

beforeEffect
afterEffect
beforeCreate
afterCreate
beforeUpdate
afterUpdate
beforeRead
afterRead
beforeDelete
afterDelete
afterError
beforeNewtQuery
beforeMongoQuery

実行順

create

Authorization -> Access -> Validation -> filterMetrics -> beforeEffect -> Optimize -> beforeCreate -> save -> afterCreate -> response

DataProvider

Authorization -> Access -> Validation -> beforeRead -> buildMongoQuery -> beforeMongoQuery -> mongoose.aggregate -> filterMetrics -> afterEffect -> afterRead -> response

read

Authorization -> Access -> Validation -> read -> filterMetrics -> afterEffect -> afterRead -> response

readMany

Authorization -> Access -> Validation -> beforeRead -> find -> filterMetrics -> afterEffect -> afterRead -> response

update

Authorization -> Access -> Validation -> filterMetrics -> beforeEffect -> Optimize -> beforeUpdate -> updateOne -> afterUpdate -> response

delete

Authorization -> Access -> Validation -> beforeDelete -> deleteOne -> afterDelete -> response

beforeEffect

NewtZeroConfigのpluginが呼ばれる直前に呼び出されます。 callbackに渡される引数・戻り値は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管します。express.jsのRequest型です。
`data`	any	リクエストデータ
`user`	User	APIリクエストしたユーザー

戻り値

カラム	型	説明
`data`	any	加工したデータを返却します。

afterEffect

データが読み込まれ、メトリクスのフィルタリング処理の直後に呼び出されます。 callbackに渡される引数・戻り値は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管します。express.jsのRequest型です。
`user`	User	APIリクエストしたユーザー
`data`	any	リクエストデータ

戻り値

カラム	型	説明
`data`	any	加工したデータを返却します。

beforeCreate

データをセーブする直前に呼び出されます。callback関数によってデータを加工し、データベースへ保存します。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`data`	any	リクエストデータ
`user`	User	APIリクエストしたユーザー

戻り値

カラム	型	説明
`data`	any	加工したデータを返却します。

afterCreate

データをセーブした直後に呼び出されます。callback関数によってレスポンスを加工し、データを返却します。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`doc`	any	保存するデータ
`user`	User	APIリクエストしたユーザーです。

戻り値

カラム	型	説明
`doc`	any	加工したデータを返却します。

beforeUpdate

データを更新する直前に呼び出されます。callback関数によってデータを加工し、データベースへ保存します。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`user`	User	APIリクエストしたユーザーです。
`data`	any	リクエストデータ

戻り値

カラム	型	説明
`data`	any	加工したデータを返却します。

afterUpdate

データを更新した直後に呼び出されます。callback関数によってレスポンスを加工し、データを返却します。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`user`	User	APIリクエストしたユーザーです。
`doc`	any	リクエストメソッド

戻り値

カラム	型	説明
`doc`	any	加工したデータを返却します。

beforeNewtQuery

DataProvider APIをリクエストする際にQueryが実行される前に呼び出されます。callback関数によってNewtQueryを加工し、データを読み込みます。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`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部分
`mql`	mongoQuery (beforeMongoQuery以外は`undefined`)

戻り値

カラム	型	説明
`newtQuery`	NewtQuery	加工したNewtQueryを返却します。

beforeMongoQuery

NewtQueryから変換されたMongoQueryが実行される前に呼び出されます。 callback関数によってMongoQueryを加工し、データを読み込みます。 callbackに渡される引数・戻り値は以下の通りです。

カラム	型	説明
`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部分
`mql`	mongoQuery (beforeMongoQuery以外は`undefined`)

戻り値

カラム	型	説明
`newtQuery`	NewtQuery	加工したNewtQueryを返却します。

beforeRead

データの読込前に、呼び出されます。callback関数によってMongoQueryを作成し、データを読み込みます。 callbackに渡される引数・戻り値は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`user`	User	APIリクエストしたユーザーです。
`id`	string	URLのパスパラメータです。リソースの一意な識別子です。

戻り値

カラム	型	説明
`MongoQuery`	any	MongoDBのデータ検索に使用するqueryを返却します。

afterRead

データの読込後、読み込んだデータを加工し、レスポンスデータとして返します。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`data`	any	リクエストデータ
`user`	User	APIリクエストしたユーザー

戻り値

カラム	型	説明
`doc`	any	加工したデータを返却します。

beforeDelete

データを削除する直前に呼び出されます。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`user`	User	APIリクエストしたユーザー
`data`	any	リクエストデータ

戻り値

カラム	型	説明
`data`	any	加工したデータを返却します。

afterDelete

データを削除した直後に呼び出されます。 callbackに渡される引数は以下の通りです。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`user`	User	APIリクエストしたユーザー
`data`	any	リクエストデータ

戻り値

カラム	型	説明
`doc`	any	加工したデータを返却します。

afterError

エラーが出力された際に呼び出されます。

カラム	型	説明
`req`	Request	リクエストメソッド・ボディ・クエリパラメータ等のリクエスト情報を保管する、express.jsのRequest型です。
`user`	User	APIリクエストしたユーザー
`data`	any	リクエストデータ
`err`	any	エラーデータ

戻り値

カラム	型	説明
`doc`	any	加工したデータを返却します。

また、callbackに渡される引数は以下の通りです。

Meta情報

カラム	型
`updatedCount`	number
`updatedTimestamp`	Date
`req.method`	リクエストメソッド
`id`	操作を行うデータの`id` or `undefined`
`newtQuery`	`NewtQuery` or `undefined`
`orderQ`	newtQueryのorder部分
`limitQ`	newtQueryのlimit部分
`skipQ`	newtQueryのskip部分
`searchQ`	newtQueryのsearch部分
`matchQ`	newtQueryのmatch部分
`mql`	mongoQuery (beforeMongoQuery以外は`undefined`)

フィールド（Metrics)のフィルタリング

GETメソッドの場合、データ返却前に metricsによって返却するフィールドを強制的にフィルタリングできます。 POST、UPDATEメソッドの場合、falseを返したフィールドは書き込まれません。（更新されません。）

type MetricsCustom {
    metricName: string;
    access?: {
        create?: (req)=>boolean;
        update?: (req)=>boolean;
        delete?: (req)=>boolean;
        read?: (req)=>boolean;
    };
}

リクエストデータのバリデーション

リクエストしたデータ(クエリパラメータ、ボディ)のデータをコールバック関数で検証できます。無効なデータがある場合、コールバック関数に戻り値を指定することで、ステータスコード400とともにレスポンスのエラーメッセージとして返却されます。

type ValidateCallback = (req, user) => any

参考:Main関数内

const nz = new NewtZero();

await nz.load();
await nz.start();

Asset v2

新機能１

保存テーブルの指定機能が追加されます。 Assetのデータは従来、RawData,TxnData,TopDataテーブルに保存されます。しかし、アプリケーションを堅牢にしたい場合、それぞれのデータを独立したテーブルに保存したくなる場合があるでしょう。新しいAssetでは保存先テーブルを指定することができる様になります。

Assetに追加された新しいフィールド

カラム	説明	値	デフォルト
`collection`	保存先テーブル	string(Collection名)	undefined
`metaTemplate`	データに付与するメタ情報のテンプレート	`gif23` or `allegrobot`	`allegrobot`
`dataFormat`	保存されるデータ型を定義します。	`separate` or `allegrobot` or `combine`	`allegrobot`

gif23 ... 政府相互運用性フレームワーク（GIF）　　

allegrobot ... 従来のAllegrobotで採用されていたメタ情報

データフォーマット

allegrobotデータフォーマット

bases:{

}

contents:{
    rawdata:{

    },
    optdata:{

    }
}

meta:{

}

orgin:{

}

metrics:{

}

Custom Endpoints

パスのID変更

デフォルトでは、read, update, deleteAPIではNewtZeroが発行したIDを指定します。これをカスタマイズするために、CollectionConfig.primaryKeyを指定することでNewtZeroの発行IDの代わりにデータの任意のフィールドを指定できます。例えば、primaryKey: "contents.rawdata.itemId"と定義した場合、 /api/1/item/:idのidは、data.contents.rawdata.itemIdを参照します。

エンドポイントの追加

NewtZeroSDKで提供するCRUD機能以外のエンドポイントを追加する場合、NewtZeroSDK.addRoute関数を利用できます。この関数はexpress.jsのapp.use()関数のwrapper関数であり、ミドルウェア関数をパスにマウントすることでエンドポイントを追加できます。

import express from "express";
import {NewtZeroSDK} from "newtzero-sdk";

const app = express();
app.use('/:id', (req, res, next) => {
  console.log('Request Type:', req.method);
  next();
})

nz = NewtZeroSDK();
nz.load();
nz.addRoute("/api/1", app);
nz.start();

Metrics v2

metricsに追加されたフィールド

カラム	説明	型
`valueType`	値の種類を指定します。指定した値に基づいて解釈エンジンがデータを解釈し、データを自動整形します。anyを指定した場合は値の整形は行われません。	any, string, date, number
`interpretationEngine`	解釈エンジンを指定します。`gpt3`...AIによって解釈します。（未リリース）`gif23`...政府相互運用性フレームワークの2023年時点の仕様に基づき解釈します。 `allegrobot`...従来の解釈エンジンです。	`gpt3`, `gif23`, `allegrobot`

nAuth

コントラクタの予約語

Group

RoleのCRUD

GroupのCRUD

Support OAuth2.0

私たちはOAuth2.0をサポートします。

開発者用ドキュメント

NewtZero

API SDK​

利用方法​

Callback​

実行順​

create​

DataProvider​

read​

readMany​

update​

delete​

beforeEffect​

afterEffect​

beforeCreate​

afterCreate​

beforeUpdate​

afterUpdate​

beforeNewtQuery​

beforeMongoQuery​

beforeRead​

afterRead​

beforeDelete​

afterDelete​

afterError​

フィールド（Metrics)のフィルタリング​

リクエストデータのバリデーション​

参考:Main関数内​

Asset v2​

新機能１​

データフォーマット​

Custom Endpoints​

パスのID変更​

エンドポイントの追加​

Metrics v2​