コンテンツAPI

GET /api/v1/{endpoint}

最終更新日: 2020/10/12

リスト形式のAPIにおいてはコンテンツ一覧が取得でき、オブジェクト形式のAPIにおいては単一コンテンツの取得ができます。

オブジェクト形式のAPIの場合はGET /api/v1/{endpoint}/{content_id}と同様の結果が得られるのでそちらをご参照ください。
ここではリスト形式のAPIの場合におけるリクエストヘッダー、クエリパラメータについて解説します。

リクエストヘッダー

X-API-KEY

GET APIリクエストの際に必要な認証キーです。リクエストヘッダーに含めて送信してください。

Information: API-KEY / WRITE-API-KEYはサービス内の全API共通となります。
そのため、クライアントサイドから直接APIを呼び出すことでユーザーがキーを把握できてしまう場合、エンドポイントさえ分かれば他のAPIも呼び出せてしまうことにご注意ください。
対処法としては、サーバサイドからAPIを呼び出す、またはJamstack構成にするなどしてキーを漏洩しないことが挙げられます。

X-GLOBAL-DRAFT-KEY

全ての下書き状態のコンテンツを一度に取得するための認証キーです。
複数の下書きコンテンツを同時に取得する必要がある場合にリクエストヘッダに値を設定して送信してください。
（通常、下書き状態のコンテンツを取得するにはコンテンツ毎に生成されたdraftKeyを使用します。）

Information: X-GLOBAL-DRAFT-KEYは漏洩しないよう管理してください。漏洩すると全ての下書き状態のコンテンツを読み取られる危険性があります。
特にクライアントサイドで利用する場合は検証環境内のみで利用するなど注意して取り扱ってください。

クエリ

URLの語尾にGETパラメータ形式で指定できます。

draftKey

下書き状態のコンテンツを取得するためのパラメータです。コンテンツの編集画面で確認できるdraftKeyをパラメータとして追加してください。
draftKeyを使って取得できる下書きコンテンツは通常1つのみです。
複数の下書き状態のコンテンツを同時に取得したい場合には認証キーであるX-GLOBAL-DRAFT-KEYをご利用ください。

limit

取得件数を指定します。
デフォルト値は10です。
上限値はありませんが、レスポンスサイズ（レスポンスヘッダのcontent-lengthの値）が約5MBを超えるとエラーが発生します。
そのため、大量のコンテンツの全件取得をしたい場合は下記のoffsetパラメータと組み合わせてページング処理を行ってください。

offset

何件目から取得するかを指定します。
デフォルト値は0です。

orders

取得するコンテンツの並び替えを行います。
並び替え対象とするフィールド名をorders=publishedAtといった形で指定してください。
複数のフィールドを並び替え対象とする場合はorders=publishedAt,-updatedAtのようにカンマ区切りで指定が可能です。

また降順を指定する場合はフィールド名の先頭に-（マイナス）を付与してください。

降順：-publishedAt
昇順：publishedAt

なお、並び替えが可能なのは以下のデータ型を持つフィールドのみです。
これ以外のフィールドを指定しても無視されます。

日付
真偽値（true or false）
数値

q

コンテンツの全文検索を行います。検索対象となるフィールドは「テキストフィールド」「テキストエリア」「リッチエディタ」です。
日本語などのマルチバイト文字列の検索を行う際はURLエンコードして値を渡す必要がありますのでご注意ください。

fields

コンテンツの中で取得する要素を指定します。
fields=title,main_image,updatedAt,author.nameのようにカンマ区切りで値を記載してください。author.organization.nameのようにドットでつないでキーを指定することで参照コンテンツの要素も指定できます。fieldsが指定されていない場合は全ての要素を取得します。

ids

コンテンツのidをfirst_id,second_id,third_idのようにカンマ区切りで指定することで対象コンテンツのみを取得できます。

filters

条件を指定することでコンテンツを絞り込んで取得できます。利用できる条件式は以下の通りです。

equals

指定に一致したコンテンツを取得します。
（例：gender[equals]women）

not_equals

指定に一致しないコンテンツを取得します。
（例：gender[not_equals]women）

less_than

指定より小さいコンテンツを取得します。
（例：createdAt[less_than]2019-11）

greater_than

指定より大きいコンテンツを取得します。
（例：createdAt[greater_than]2019-10）

contains

指定した値を含むコンテンツを取得します。
（例：title[contains]おすすめ）

exists

指定した値が存在するコンテンツを取得します。
（例：nextLink[exists]）

not_exists

指定した値が存在しないコンテンツを取得します。
（例：nextLink[not_exists]）

begins_with

指定した値から始まるコンテンツを取得します。
（例：publishedAt[begins_with]2019-11）

なおコンテンツ参照については単数の場合は[equals]（例：category[equals]uN28Folyn）、複数の場合は[contains]のみが利用可能です。（例：tags[contains]oJIZmiban）
その場合は{VALUE}部分に対象のコンテンツのidを入力してください。

また、カスタムフィールドの場合は{フィールド名}.{カスタムフィールドのフィールド名}[equals]{VALUE}といった形でフィールド内の値を対象に絞り込みが可能です。
同様に繰り返しフィールドの場合は{フィールド名}.{カスタムフィールドのフィールドID}.{カスタムフィールドのフィールド名}[contains]{VALUE}とすることで繰り返しフィールド内の値を対象に絞り込みが可能です。

最後に条件式は[and]（AND条件) もしくは[or]（OR条件)で区切ることで複数指定ができます。
条件式を括弧()で囲って一部の式を優先させることもできますので、適切な値が取れるよう優先順位をコントロールしてください。

例：カテゴリーがエンジニアリングかつ、2019/11/14以降またはタイトルが存在している記事を抽出

$curl --glob "https://{your-service}.microcms.io/api/v1/blog?filters=category[equals]engineering[and](date[begins_with]2019-11-14[or]title[exists])" -H "X-API-KEY: {api-key}"

depth

参照コンテンツを取得する階層の深さを指定します。
デフォルト値は1、最大値は3です。

例えば、ブログコンテンツに関連記事を表示するために、自分自身を循環参照しているとします。

例）depth = 1の場合

{
  "id": "id1",
  "title": "title1",
  "body": "body1",
  "related_blog": {
    "id": "id2",
    "title": "title2",
    "body": "body2",
    "related_blog": {
      "id": "id3"
    }
  }
}

例）depth = 2の場合

{
  "id": "id1",
  "title": "title1",
  "body": "body1",
  "related_blog": {
    "id": "id2",
    "title": "title2",
    "body": "body2",
    "related_blog": {
      "id": "id3",
      "title": "title3",
      "body": "body3",
      "related_blog": {
        "id": "id4"
      }
    }
  }
}