ver.2サポートサイト

参照先フィールドを含めたレコード取得API

機能概要

従来のレコード取得APIにおいては、参照先情報も含めて取得する場合は、
参照元DBのレコードを一度取得し、別途、参照先情報をリクエストする必要がありましたが、
新たに追加された参照先フィールドを含めたレコード取得APIを活用することで、
参照元DBのフィールドに加え、参照先DBのフィールドや参照先DBのさらに参照先のフィールド値を1リクエストでまとめて取得できるようになります。
APIの記述方法についてはサンプルプログラムやAPIリファレンスをご覧ください。

例えば、以下のようなことが実現できます。
　・セミナーマスタとセミナー申込DBがある場合に、セミナー情報も含んだ申込履歴情報を1リクエストで取得する。
　・セミナーマスタとセミナー講師マスタ、セミナー申込DBがある場合に、セミナー情報と講師情報を含んだ申込履歴情報を1リクエストで取得する。

仕様

APIの種類

フィールド指定形式

参照先DBのフィールドを取得する場合は{参照フィールド識別名}.{参照先DBのフィールド識別名}の形式で記載します。

参照先DBのフィールド指定例

fields=referenceField.textField

参照先DBのさらに参照先のフィールドを取得する場合は{参照フィールド識別名}.{参照先DBの参照フィールド識別名}.{先の先のフィールド識別名}の形式で記載します。
参照先DBの参照先のフィールド指定例

fields=referenceField_1.referenceField_2.textField

出力形式

参照先フィールドを含めたレコード一覧を取得 Response例

{
    "items": [
        {
            "_id": "1",
            "_revision": "1",
            "_createdBy": { ... },
            "_createdAt": "2023-03-24T05:38:25Z",
            "_updatedBy": { ... },
            "_updatedAt": "2023-03-24T05:39:42Z"
            "textField": "text",
            "singleReferenceField": "1",
            "singleReferenceField._id": "1",
            "singleReferenceField.textField": "text",
            "multiReferenceField": ["1","2"],
            "multiReferenceField._id": ["1","2"],
            "multiReferenceField.textField": ["text",null],
            "singleReferenceField.singleReferenceField_1": "1"
            "singleReferenceField.singleReferenceField_1._id": "1"
            "singleReferenceField.singleReferenceField_1.textField": "text"
        }
    ],
    "options": {},
    "prevOffset": null,
    "nextOffset": null,
    "totalCount": 1
}

Response取得例

$decoded = json_decode($response, true);
$field           = $decoded["items"][0]["textField"];
$single_refField = $decoded["items"][0]["singleReferenceField.textField"];
$multi_refField  = $decoded["items"][0]["multiReferenceField.textField"][0];
$ref_refField    = $decoded["items"][0]["singleReferenceField.singleReferenceField_1.textField"];

参照先フィールドを含めたレコード Response例

{
    "item": {
            "_id": "1",
            "_revision": "1",
            "_createdBy": { ... },
            "_createdAt": "2023-03-24T05:38:25Z",
            "_updatedBy": { ... },
            "_updatedAt": "2023-03-24T05:39:42Z"
            "textField": "text",
            "singleReferenceField": "1",
            "singleReferenceField._id": "1",
            "singleReferenceField.textField": "text",
            "multiReferenceField": ["1","2"],
            "multiReferenceField._id": ["1","2"],
            "multiReferenceField.textField": ["text",null],
            "singleReferenceField.singleReferenceField_1": "1"
            "singleReferenceField.singleReferenceField_1._id": "1"
            "singleReferenceField.singleReferenceField_1.textField": "text"
    },
    "options": {}
}

Response取得例

$decoded = json_decode($response, true);
$field           = $decoded["item"]["textField"];
$single_refField = $decoded["item"]["singleReferenceField.textField"];
$multi_refField  = $decoded["item"]["multiReferenceField.textField"][0];
$ref_refField    = $decoded["item"]["singleReferenceField.singleReferenceField_1.textField"];

セレクトフィールド、マルチセレクトフィールドのラベル出力例

optionのオブジェクトとして出力されます。

"options": {
    "selectField": {
        "1": "ラベル1",
        "2": "ラベル2",
        "3": "ラベル3"
    },
    "singleReferenceField.selectField": {
        "1": "ラベルa",
        "2": "ラベルb",
        "3": "ラベルc"
    },
    "singleReferenceField.singleReferenceField_1.selectField": {
        "1": "ラベルI",
        "2": "ラベルII",
        "3": "ラベルIII"
    },
    "multiReferenceField.selectField": {
        "1": "ラベルA",
        "2": "ラベルB",
        "3": "ラベルC"
    }
}

フィールド出力可能な参照方法

参照フィールドの参照方法によりフィールドの指定可否が変わります。

指定可能なフィールドタイプ

参照先DBや参照先DBの参照先のフィールドの指定制限

・fieldsパラメータで指定可能なフィールド数は自DB、参照先DB、参照先DBの参照先フィールド含め合計150フィールドまでです。

・参照フィールド（複数レコード参照）の参照先フィールドは、1つの参照フィールドにつき5フィールドまで指定可能です。

・参照フィールドは合計で5フィールドまで指定可能です。

　※参照先DBや参照先DBの参照先のフィールドを指定したことにより、同一参照フィールドを複数回指定した場合は1フィールドとしてカウントします。
　　ただし複数の自DBの参照フィールドから1つの参照先DBの参照フィールドを複数回指定している場合は、自DBの参照フィールド毎に別フィールドとしてカウントします。

参照フィールドカウント例1

下記のフィールドを指定した場合、参照フィールドの合計は5フィールドとなる

fields=
セミナー申込DBの参照フィールド1,
セミナー申込DBの参照フィールド1.セミナーマスタDBのテキスト1,
セミナー申込DBの参照フィールド1.セミナーマスタDBの参照フィールド1,
セミナー申込DBの参照フィールド1.セミナーマスタDBの参照フィールド1.講師DBのテキスト1,
セミナー申込DBの参照フィールド1.セミナーマスタDBの参照フィールド2,
セミナー申込DBの参照フィールド1.セミナーマスタDBの参照フィールド2.会場DBのテキスト1,
セミナー申込DBの参照フィールド1.セミナーマスタDBの参照フィールド2.会場DBのテキスト2,
セミナー申込DBの参照フィールド2,
セミナー申込DBの参照フィールド2.会員DBのテキスト1,
セミナー申込DBの参照フィールド2.会員DBのテキスト2,
セミナー申込DBの参照フィールド3,
セミナー申込DBの参照フィールド3.関連部署DBのテキスト1

内訳

1.セミナー申込DBの参照フィールド1
2.セミナー申込DBの参照フィールド2
3.セミナー申込DBの参照フィールド3
4.セミナーマスタDBの参照フィールド1
5.セミナーマスタDBの参照フィールド2

参照フィールドカウント例2

下記のフィールドを指定した場合、参照フィールドの合計は5フィールドとなる

fields=
セミナー申込DBの参照フィールド1,
セミナー申込DBの参照フィールド1.セミナーマスタDBのテキスト1,
セミナー申込DBの参照フィールド1.セミナーマスタDBの参照フィールド1,
セミナー申込DBの参照フィールド1.セミナーマスタDBの参照フィールド1.講師DBのテキスト1,
セミナー申込DBの参照フィールド2,
セミナー申込DBの参照フィールド2.セミナーマスタDBのテキスト1,
セミナー申込DBの参照フィールド2.セミナーマスタDBの参照フィールド1,
セミナー申込DBの参照フィールド2.セミナーマスタDBの参照フィールド1.講師DBのテキスト1,
セミナー申込DBの参照フィールド3,
セミナー申込DBの参照フィールド3.関連部署DBのテキスト1

内訳

1.セミナー申込DBの参照フィールド1
2.セミナー申込DBの参照フィールド2
3.セミナー申込DBの参照フィールド3
4.セミナーマスタDBの参照フィールド1（参照元の参照フィールドがセミナー申込DBの参照フィールド1）
5.セミナーマスタDBの参照フィールド1（参照元の参照フィールドがセミナー申込DBの参照フィールド2）

※講師DBのテキスト1を2回指定し、2回ともセミナーマスタDBの参照フィールド1を参照しているが、参照元の参照フィールドが異なるため別フィールドとしてカウントする

既存のレコード一覧取得API、レコード取得APIとの比較

※1　fieldsパラメータで指定したフィールドが出力されます。
　　 fieldsを使用しない場合、自DBの出力可能なフィールドが全て出力されますが、参照先DBや参照先DBの参照先のフィールドは出力されません。
　 　参照先DBや参照先DBの参照先のフィールドを使用する場合はfieldsパラメータでフィールドを指定してください。

※2　fieldsパラメータで指定するフィールドはリクエストするAPIエージェントに下記の閲覧権限が必要です。
　 　・アプリロール＞フィールド権限＞閲覧権限
　 　・（参照先DBや先の先のフィールドを指定する場合）参照元のアプリロール＞参照フィールドのフィールド権限＞閲覧権限
　 　フィールド閲覧権限が無い場合、403エラーを返します。

※3　参照先フィールドを含めたレコード一覧取得API、参照先フィールドを含めたレコード取得APIで

　 　参照先DBや参照先DBの参照先の「_id」やフィールド値を出力する場合、下記の閲覧権限が必要です。
　 　・参照先DBや参照DBの参照先のアプリロール＞レコード閲覧権限
　 　レコード閲覧権限が無い場合、nullを返します。

　 　参照元DBの参照フィールドは参照先のレコード閲覧権限が無い場合でも参照しているレコードIDを出力する為、

　 　参照しているレコードIDと参照先DBや参照先DBの参照先の「_id」やフィールド値を比較することで、参照先DBのレコード閲覧権限の有無を確認することが出来ます。
　 　例）自DBの複数レコード参照の参照フィールド、参照先DBの「_id」とフィールド値のレスポンスが下記だった場合、
　　　　 ID1はレコード閲覧権限あり、ID2はレコード閲覧権限なし となります。

"multiReferenceField": ["1","2"],
"multiReferenceField._id": ["1",null],
"multiReferenceField.textField": ["text",null],

※4　レコード一覧を取得 自DB参照フィールドのResponse例

"singleReferenceField": {
    "url": "https://api.spiral-platform.com/v1/apps/XXX/dbs/123/records?referrer=123.4:56"
},
"multiReferenceField": {
    "url": "https://api.spiral-platform.com/v1/apps/XXX/dbs/123/records?referrer=123.7:56"
},

※5　参照先フィールドを含めたレコード一覧を取得、参照先フィールドを含めたレコードを取得 自DB参照フィールドのResponse例

"singleReferenceField": "1",
"multiReferenceField": ["1","2"],

※6　レコードを取得 自DB参照フィールドのResponse例

"singleReferenceField": {
    "info": {
        "url": "https://api.spiral-platform.com/v1/apps/XXX/dbs/123/records?referrer=123.4:56"
    },
    "value": {
        "_id": "1",
        "_unauthorized": false,
        "_revision": "10",
        "_createdBy": { ... },
        "_createdAt": "2020-04-30T17:06:29Z",
        "_updatedBy": { ... },
        "_updatedAt": "2020-04-30T17:06:29Z"
    }
},
"multiReferenceField": {
    "info": {
        "url": "https://api.spiral-platform.com/v1/apps/XXX/dbs/123/records?referrer=123.7:56"
    },
    "value": [
        {
            "_id": "2",
            "_unauthorized": false,
            "_revision": "10",
            "_createdBy": { ... },
            "_createdAt": "2020-04-30T17:06:29Z",
            "_updatedBy": { ... },
            "_updatedAt": "2020-04-30T17:06:29Z"
        },
        {
            "_id": "3",
            "_unauthorized": false,
            "_revision": "10",
            "_createdBy": { ... },
            "_createdAt": "2020-04-30T17:06:29Z",
            "_updatedBy": { ... },
            "_updatedAt": "2020-04-30T17:06:29Z"
        }
    ]
},

その他制限事項

・本APIはver.1.1で利用できます。

・ソート対象（sortパラメータ）に指定可能なフィールドは自DBのフィールドのみです。

・抽出条件（whereパラメータ）に指定可能なフィールドは自DBのフィールドのみです。