LoginSignup
0

More than 5 years have passed since last update.

Storyblokのdocs翻訳チャレンジその10!!!

Posted at

ソース

Stories

Storyblokで使われる殆どのエンドポイントは、低レイテンシと最適なアベイラビリティのために調整されています。

世界中で低いレイテンシを得るために、StoryblokはAPIにCDNを使っています。公式のStoryblok SDKは既にキャッシュの無効化に対応し、自分で実装する必要はありません。しかしAPIを手動で呼ぶのであれば、cvパラメータをコンテンツの最新版を取得するStory APIに追加する必要が出てきます。

spaces API、またはタイムスタンプを用いたキャッシュ無効化

  1. まず、/v1/cdn/spaces/meを呼びspace.version属性を取得します。この操作の代わりにタイムスタンプを生成することも出来ます。
  2. そのspace.versionをその後の/v1/cdn/storiesの呼び出し全てのcvパラメータに使用します。
  3. サーバーサイドアプリケーションでは、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:00
lt-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"
  }
}

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0