Developers

シート検索(Search API)におけるtargetsの概念と指定方法

targetsは、シート検索時に返却対象とする属性をキーで指定するものです。
targetsは、検索対象となっているシート、および検索対象となっているシートの紐づき項目に対して指定します。

検索対象アイテムキーの指定

検索対象としたいアイテムキーは、targetColsに指定します。
※各シートの主キー項目は、targetColsに指定しない場合でも、レスポンスに含まれます。

紐づき先シートの項目を指定する場合

シートの紐づき関係についての説明はこちら

紐づき先シートの項目を指定したい場合、targetColsに紐づき項目の指定が必須となります。
例)案件の紐づき顧客の顧客名を指定したい場合、案件の紐づき顧客(relational_customer)自体を指定したうえで、顧客名を指定する必要があります。

targets内の1objectのtargetColsには、1階層分の項目しか指定できないため、紐づき先シート(別階層シート)の項目を指定する場合はobjectを分ける必要があります。
例)案件の紐づき顧客の項目を指定したい場合、案件のobjectと、顧客のobjectは分ける。

紐づき先シートの項目を指定するobjectのrelationItemDefKeyには、上位層のtargetColsにて指定した紐づき項目を指定します。
一階層目のobjectのrelationItemDefKeyはnullを指定します。
例)案件の紐づき顧客の項目を指定する場合、一階層目である案件のobjectはrelationItemDefKeyをnullで指定し、二階層目の顧客のobjectには、一階層目である案件のtargetColsにて指定した、紐づき顧客項目を指定します。

紐づき先シートの項目を指定するobjectのtargetColsには、一階層目の紐づき項目と、二層目の対象の項目のアイテムキーを@で連結したキーを指定します。
例)案件の紐づき顧客の顧客を指定したい場合、顧客のobjectのtargetColsには、businessplans.businessplan.relational_customer@customers.customer.nameを指定します。

Example

一階層目のみ指定

一階層目のみ指定する場合、targetColsに指定したもの(主キー項目は未指定の場合で必ず含まれます)のみ返却されます。

Request Body
{
    //中略
    "targets": [
        {
            "relationItemDefKey": null, //一階層目なのでnull
            "targetCols": [
                "businessplans.businessplan.id",
                "businessplans.businessplan.name"
          ]
        }
    ]
}
Response Body
[
    {
        "businessplans.businessplan.id": 123,
        "businessplans.businessplan.name": "案件名"
    }
]

一階層目とその紐づき項目のみ指定

一階層目とその紐づき項目のみ指定する場合、二階層目は主キー項目のみ返却されます。

Request Body
{
    //中略
    "targets": [
        {
            "relationItemDefKey": null, //一階層目なのでnull
            "targetCols": [
                "businessplans.businessplan.id",
                "businessplans.businessplan.name",
                "businessplans.businessplan.relational_customer" //一階層目の紐づき項目
          ]
        }
    ]
}
Response Body
[
    {
        "businessplans.businessplan.id": 123,
        "businessplans.businessplan.name": "案件名",
        "businessplans.businessplan.relaitonal_customer": [
            {
                "businessplans.businessplan.relational_customer@customers.customer.id": 123 //二階層目は主キー項目のみ
            }
        ]
    }
]

二階層目の項目を指定する

二階層目の項目を指定する場合、二階層目もtargetColsに指定した項目が返却されます。

Request Body
{
    //中略
    "targets": [
        {
            //案件
            "relationItemDefKey": null, //一階層目なのでnullを指定する。
            "targetCols": [
                "businessplans.businessplan.relational_customer" //案件の紐づき顧客の指定が必須。
          ]
        },
        {
            //案件の紐づき顧客
            "relationItemDefKey": "businessplans.businessplan.relational_customer", //案件の紐づき顧客項目を指定。上位層のtargetColsにて指定していることが前提。
            "targetCols": [
                "businessplans.businessplan.relational_customer@customers.customer.name" //案件の紐づき顧客の顧客名。一階層目(案件)の紐づき顧客(businessplans.businessplan.relational_customer)と、二階層目(顧客)の顧客名(customers.customer.customer_name)を@で連結したキー
            ]
        }
    ]
}
Response Body
[
    {
        "businessplans.businessplan.id": 123, //主キー項目は必ず返却される。
        "businessplans.businessplan.relaitonal_customer": [
            {
                "businessplans.businessplan.relational_customer@customers.customer.id": 456, //主キー項目は必ず返却される。
                "businessplans.businessplan.relational_customer@customers.customer.name": "顧客名" //二階層目のtargetColsに指定した項目
            }
        ]
    }
]