ソース
Stories
Storyblokで使われる殆どのエンドポイントは、低レイテンシと最適なアベイラビリティのために調整されています。
世界中で低いレイテンシを得るために、StoryblokはAPIにCDNを使っています。公式のStoryblok SDKは既にキャッシュの無効化に対応し、自分で実装する必要はありません。しかしAPIを手動で呼ぶのであれば、cv
パラメータをコンテンツの最新版を取得するStory APIに追加する必要が出てきます。
spaces API、またはタイムスタンプを用いたキャッシュ無効化
- まず、
/v1/cdn/spaces/me
を呼びspace.version
属性を取得します。この操作の代わりにタイムスタンプを生成することも出来ます。 - そのspace.versionをその後の/v1/cdn/storiesの呼び出し全ての
cv
パラメータに使用します。 - サーバーサイドアプリケーションでは、
space.version
をファイルに保存し、publishedイベントをリッスンしてファイルを更新することをオススメします。
storiesのリストを取得
エンドポイント
GET /v1/cdn/stories
パラメーター
名前 | 説明 |
---|---|
token(必須) | publishedだけ欲しければpublicトークン draftも欲しければprivateトークン |
with_tag | 任意の(複数の)タグでフィルタ カンマ区切りで複数タグ 例: with_tag=featured,home |
is_startpage | フォルダのスタートページでフィルタ 1でスタートページのみを返す 0でスタートページを除外して返す |
starts_with | slugでフィルタ 特定のフォルダの全エントリを取り出すのに使用可能 例: starts_wih=de,starts_with-en/news |
by_uuids | コンマ区切りのIDで(複数の)ストーリーを取得 例: by_uuids=52323-…,52323-… |
excluding_ids | コンマ区切りのIDで(複数の)ストーリーを除外 例: excluding_ids=5,8 |
excluding_fields | コンマ区切りの名前で、コンテンツタイプから任意のフィールドを除外 例: excluding_fields=title,body |
version | Publishedもしくはdraftバージョン 値として'draft'と'published'だけを取る |
cv | キャッシュバージョン 重要: 最新のPublishedバージョンを取得したい場合に必須 詳しくはこのページの最初へ。 |
sort_by | エントリーを任意の属性でソートしcontent.YOUR_FIELD:asc (昇順)content.YOUR_FIELD.desc (降順)で並び替える。エントリの全てのルート属性をソートに使用でき、また区切り文字としてドットを使うことで content に入っているコンテンツタイプの全てのフィールドへアクセスして使用可能。例: 'position:asc', 'content.your_custom_field:asc', 'created_at:desc' |
search_term | コンテンツアイテムの全文検索 |
filter_query | コンテンツタイプの任意の属性でフィルタ フィルタークエリーパラメータにクエリーオペレーションキーを格納する必要がある 複数の値でフィルタする場合、カンマ区切り filter_query[YOUR_ATTRIBUTE] [OPERATION_KEY]-VALUE,VALUE 以下のフィルターオペレーションの{OPERATION_KEY's}が在る all -文字列値の値全てを格納in -文字列値の値のうち1つをexists -アレイ値の値のうち1つを格納gt-date -日付が新しいもの(greater than) フォーマット: 2018-03-03 10:00lt-date -日付が古いもの(less than)gt-num -数値が大きいlt-num -数値が小さい例: コンテンツタイプpageかつnews: filter_query[component][all]=page,news コンテンツpageまたはnews: filter_query[component][in]=page,news 白いスタイル(styles is ['white','shiny']): filter_query[styles][exists]=white より新しい: filter_query[custom_date][gt-date]=2018-03-03 10:00 レートが4以上: filter_query[rating][gt-num]=4 |
resolve_links | resolve_link=1の場合、自動でマルチリンクフィールドタイプの内部リンクの解決が行われる Storyごとの解決されたリンクの限度は50 |
resolve_relations | マルチオプション、もしくはシングルオプションフィールドタイプの他のストーリーのリレーションシップを解決 フィールドのキーをカンマ区切りの文字列で渡すことで任意のフィールドを解決できる 例: authors,comments |
page | 任意のページを取得 |
試してみる
Run in postman //todo
リクエスト
クエリーパラメーター
token=wANpEQEsMYGOwLxwXQ76Ggtt
with_tag=red
starts_with=de/
excluding_ids=5,6
excluding_fields=title
version=published
cv=1514926039
sort_by=name:asc
filter_query[component][all]=page
per_page=10
page=0
cURL
curl "https://api.storyblok.com/v1/cdn/stories?token=wANpEQEsMYGOwLxwXQ76Ggtt&with_tag=red&starts_with=de%2F&excluding_ids=5%2C6&excluding_fields=title&version=published&cv=1514926039&sort_by=name%3Aasc&filter_query[component][all]=page&per_page=10&page=0" -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json"
レスポンス
ボディー
{
"stories": [
{
"name": "Home2",
"created_at": "2018-01-02T20:47:18.945Z",
"published_at": "2018-01-02T20:47:18.953Z",
"alternates": [
],
"id": 1887,
"uuid": "45e4cf79-99ea-4771-a50d-58155a9a1d30",
"content": {
"_uid": "7b870b36-7512-40ef-bad3-e2cbb7513cba",
"body": [
],
"component": "page"
},
"slug": "de",
"full_slug": "de/",
"sort_by_date": null,
"tag_list": [
"spicy",
"red"
],
"is_startpage": true,
"parent_id": 1886,
"meta_data": null,
"group_id": "7e44dd68-ef43-40e1-8814-aae4af7188b1"
}
]
}
idでストーリーを取得
このエンドポイントはStoryを1つ取得する場合に使われます。エンドポイントがパス(例えば: homeやariticle/blog-post-xy)やリクエストURL中のuuidを受け取ると、Storyオブジェクトが返さえます。
例:
/v1/cdn/stories/article/blog-post-xy
/v1/cdn/stories/90b2172-3e61-4a1a-822c-e06d381cce07?find_by=uuid
エンドポイント
GET /v1/cdn/stories/:story_id
パラメータ
名前 | 説明 |
---|---|
token(必須) | publishedだけ欲しければpublicトークン draftも欲しければprivateトークン |
story_id | 文字列の場合full_slugを用いてStoryを1つ探す 数値の場合idを用いてStoryを1つ探す find_byパラメータがuuidの場合、uuidでStoryを1つ探す |
find_by | 値をuuidとして与えられたとき、story_idがidとfull_slugの代わりにuuidになる 例: find_by=uuid |
version | Publishedもしくはdraftバージョン 値として'draft'と'published'だけを取る |
resolve_links | resolve_link=1の場合、自動でマルチリンクフィールドタイプの内部リンクの解決が行われる Storyごとの解決されたリンクの限度は50 |
resolve_relations | マルチオプション、もしくはシングルオプションフィールドタイプの他のストーリーのリレーションシップを解決 フィールドのキーをカンマ区切りの文字列で渡すことで任意のフィールドを解決できる 例: authors,comments |
cv | キャッシュバージョン 重要: 最新のPublishedバージョンを取得したい場合に必須 詳しくはこのページの最初へ。 |
試してみる
Run in Postman //todo
リクエスト
クエリパラメーター
token=wANpEQEsMYGOwLxwXQ76Ggtt
cURL
curl "https://api.storyblok.com/v1/cdn/stories/de?token=wANpEQEsMYGOwLxwXQ76Ggtt" -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json"
レスポンス
ボディー
{
"story": {
"name": "Home2",
"created_at": "2018-07-20T08:34:41.426Z",
"published_at": "2018-07-20T08:34:41.451Z",
"alternates": [
],
"id": 1036,
"uuid": "1f4b30ec-e6f4-48ff-a413-52f04e6da4d3",
"content": {
"_uid": "f41b3dde-5216-44b4-b84a-faa3f16760a4",
"body": [
],
"author": "c005fe81-9b55-4a5e-be05-ad05a070ebef",
"headline": "tom",
"component": "page"
},
"slug": "de",
"full_slug": "de/",
"sort_by_date": null,
"position": 0,
"tag_list": [
"spicy",
"red"
],
"is_startpage": true,
"parent_id": 1035,
"meta_data": null,
"group_id": "a0a7d221-2767-4592-81c7-40aaef133249"
}
}