参照の先も一緒に取る

参照のフィールドは、参照先のエントリーをその場に入れて返します。何段先まで入れるかは include で決めます。記事と著者のように、別のコンテンツタイプのエントリーを 1 回の呼び出しで取り出せます。

前提

［読み取り］の権限のある API キー。発行のしかたは API キーを作る、権限を決めるにあります
参照のフィールドを持つコンテンツタイプ。作り方はコンテンツタイプを作るにあります

下の例では、コンテンツタイプ「posts」に、コンテンツタイプ「authors」を指す参照のフィールド「author」があるとします。<ホスト名> をあなたの環境のホスト名に、<API キー> を API キーに置き換えてください。

参照先を取る

何も付けずに取り出すと、参照先が 1 段目まで入ります（include の既定は 1）。

curl https://<ホスト名>.hakocms.net/api/v1/content/posts/hello \
  -H "Authorization: Bearer <API キー>"

author に、著者のエントリーが入って返ります。著者のエントリーがさらに参照しているもの（ここでは mentor）は、sys の id と contentType だけになります（日時などは省いています）。

{
  "sys": { "id": "hello", "contentType": "posts", "version": 3 },
  "title": "こんにちは",
  "author": {
    "sys": { "id": "kohei", "contentType": "authors", "version": 1 },
    "name": "Kohei",
    "mentor": { "sys": { "id": "taro", "contentType": "authors" } }
  }
}

複数参照のフィールドは、参照先のエントリーの配列で返ります。

何段先まで取るかを決める

include に 0〜3 の数を付けます。

`include`	返るもの
`0`	参照先を入れない。`{ "sys": { "id", "contentType" } }` だけ
`1`（既定）	参照先のエントリーまで
`2`	参照先が参照しているエントリーまで
`3`	さらにその先まで

著者の mentor の先まで取るときは、include=2 を付けます。

curl -G https://<ホスト名>.hakocms.net/api/v1/content/posts/hello \
  -H "Authorization: Bearer <API キー>" \
  -d include=2

一覧と 1 件、シングルのどれにも使えます。

参照先のエントリー ID だけが要るときは、include=0 にすると応答が小さくなります。

参照先のフィールドを選ぶ

select で、参照先のフィールドもドットでたどって選べます。

curl -G https://<ホスト名>.hakocms.net/api/v1/content/posts/hello \
  -H "Authorization: Bearer <API キー>" \
  --data-urlencode "select=sys.id,title,author.name"

次のように返ります。

{
  "sys": { "id": "hello" },
  "title": "こんにちは",
  "author": { "name": "Kohei" }
}

複数参照のフィールドでは、配列の各要素に同じ選び方が当たります。

参照先で絞り込む

参照のフィールドは、参照先のエントリー ID で絞り込めます。著者が「kohei」の記事に絞り込みます。

curl -G https://<ホスト名>.hakocms.net/api/v1/content/posts \
  -H "Authorization: Bearer <API キー>" \
  --data-urlencode 'where=author = "kohei"'

参照先のフィールドで絞り込むこと（author.name = "Kohei" など）は、まだできません。400 が返ります。

参照先が返らないとき

参照先のエントリーが読めないときは、返りません。

参照先を公開していない、公開をやめた、または削除したときが当たります
参照のフィールドなら、キーごと返りません
複数参照のフィールドなら、読めないエントリーが配列から除かれます

参照先が返らないときは、参照先のエントリーが［公開中］になっているかを確かめてください。

preview=true を付けて下書きを読むときは、参照先も下書き（一度も公開していないものも）を読みます。くわしくは下書きを取る（プレビュー）にあります。

確かめる

author に name などのフィールドが入って返れば、参照先を取り出せています。sys だけが返るときは、include の段数が足りません。