リスト形式のAPIにおいてはコンテンツ一覧が取得でき、オブジェクト形式のAPIにおいては単一コンテンツの取得ができます。
オブジェクト形式のAPIの場合はGET /api/v1/{endpoint}/{content_id}と同様の結果が得られるのでそちらをご参照ください。
ここではリスト形式のAPIの場合におけるリクエストヘッダー、クエリパラメータ、レスポンスについて解説します。
GET APIリクエストの際に必要な認証キーです。
デフォルト権限もしくは個別権限で「GET」を有効にして、リクエストヘッダーに含めて送信してください。
X-MICROCMS-API-KEYが判別できると、第三者による不正なコンテンツの操作が可能となります。お取り扱いには十分ご注意ください。詳細は「APIキー（APIの認証と権限管理）」をご覧ください。
本APIには下記に示すパラメータを指定できます。
なお、各フィールドごとに指定可能なクエリパラメータの一覧について「GET APIにおけるクエリパラメータの指定」をご覧ください。
クエリパラメータを付与した上で、値を指定しなかった場合は、クエリパラメータを指定しない場合と同様の挙動となります。
例：limit= と指定した場合、limitはデフォルト値の10
レスポンスサイズ（レスポンスヘッダのcontent-lengthの値）が約5MBを超えるとエラーが発生します。
全件取得など、101件以上のコンテンツを取得したい場合の方法については、「101件以上のコンテンツを取得するにはどうしたらよいですか？」をご参照ください。
コンテンツを取得開始する位置を、指定した値だけ後ろにずらします。
デフォルト値は0です。
取得するコンテンツの並び替えを行います。
デフォルトは管理画面のコンテンツの表示順です（qパラメータを除く）。
並び替え対象とするフィールド名をorders=publishedAt の形式で指定してください。
また、降順を指定する場合はフィールド名の先頭に -（マイナス） を付与してください。
-publishedAtpublishedAtさらに、複数のフィールドを並び替え対象とする場合は orders=publishedAt,-updatedAt のようにカンマ区切りで指定してください。
ordersパラメータで並び替えを行う対象のフィールドの値が同じだった場合、返却されるコンテンツの順序は定まっておりません。この場合、並び順を明示的に制御するには、orders=publishedAt,-updatedAt のように複数のフィールドを並び替えの対象にする方法をご検討ください。
並び替えが可能なのは以下のフィールド、並び順となります。
これ以外のフィールドを指定した場合の挙動は不定となります。
createdAtpublishedAtupdatedAtrevisedAtsystem:default（管理画面のコンテンツ表示順）カスタムフィールドが複数挿入されている場合、降順と昇順で並び替えに使用される値が異なります。
値の中で、最も大きい値を基準にして降順で並び替えられます。
値の中で、最も小さい値を基準にして昇順で並び替えられます。
qパラメータによる検索は、コンテンツ内容をもとに作成された、全文検索用のデータを対象に実施されます。全文検索の仕様上、大文字・小文字、記号、スペース、文字列の区切り方などによって検索結果が変わる場合があります。特定のフィールドに対して、文字列の正確な部分一致検索が必要な場合は、filtersパラメータのcontainsの使用をご検討ください。
コンテンツの中で取得する要素を指定します。
fields=title,main_image,updatedAt,author.nameのようにカンマ区切りで値を記載してください。author.organization.nameのようにドットでつないでキーを指定することで参照コンテンツの要素も指定できます。fieldsが指定されていない場合は全ての要素を取得します。
カスタムフィールド内のフィールドについては、指定できません。
現在、filters内で指定する条件において、文字列のエスケープはできない仕様となっております。予めご了承ください。
指定に一致したコンテンツを取得します。
（例：gender[equals]women）
指定に一致しないコンテンツを取得します。
（例：gender[not_equals]women）
指定した値を含むコンテンツを取得します。
（例：title[contains]おすすめ）
指定した値を含まないコンテンツを取得します。
（例：title[not_contains]おすすめ）
containsと同様の注意事項がございますので、ご確認ください。
指定より小さいコンテンツを取得します。
（例：createdAt[less_than]2023-11-23T03:00:00Z、count[less_than]25）
指定より大きいコンテンツを取得します。
（例：createdAt[greater_than]2023-11-23T03:00:00Z、count[greater_than]25）
指定した値が存在するコンテンツを取得します。
（例：nextLink[exists]）
指定した値が存在しないコンテンツを取得します。
（例：nextLink[not_exists]）
指定した値から始まるコンテンツを取得します。
（例：publishedAt[begins_with]2023-11）
検索対象が数字フィールドの場合はヒットしません。
コンテンツ参照/複数コンテンツ参照を使用していて、参照先のコンテンツによって絞り込みを行う場合、
をご利用ください。
また絞り込みの条件には、コンテンツIDを使用してください。その他の値は利用できません。
カスタムフィールドの場合は、{フィールドID}.{絞り込みに用いるフィールドID}[equals]{VALUE}とすることで、カスタムフィールド内の値を対象に絞り込みが可能です。
繰り返しフィールドの場合は、{フィールドID}.{カスタムフィールドID}.{絞り込みに用いるフィールドID}[contains]{VALUE}とすることで、繰り返しフィールド内の値を対象に絞り込みが可能です。
条件式は[and]（AND条件) もしくは[or]（OR条件)で 区切ることで複数指定ができます。
条件式を括弧()で囲って一部の式を優先させることも可能です。
例：カテゴリーがエンジニアリングかつ、2019/11/14以降またはタイトルが存在している記事を抽出
$ curl "https://{your-service}.microcms.io/api/v1/blog?filters=category[equals]engineering[and](date[begins_with]2019-11-14[or]title[exists])" -H "X-MICROCMS-API-KEY: {api-key}"上記で付与されている各クエリパラメータは一部の例ですので、実際に利用可能なクエリパラメータについては、「GET APIにおけるクエリパラメータの指定」をご覧ください。
参照コンテンツを取得する階層の深さを指定します。
最小値は0で、最大値は3です。
デフォルト値は1です。
例えば、ブログコンテンツに関連記事を表示するために、自分自身を循環参照しているとします。
例）depth = 0の場合
{
"id": "id1",
"title": "title1",
"body": "body1",
"related_blog": {
"id": "id2"
}
}
例）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"
}
}
}
}旧リッチエディタのレスポンス形式を変更できます。
（現行のリッチエディタは対応していないため、ご注意ください。）
richEditorFormatに html を指定した場合、HTMLとして取得できます。
デフォルトの設定になっており、パラメータに何も指定しない場合もこちらが適用されます。
{
"title": "更新情報",
"content": "<h2 id=\"h5ca2740170\">Hello World</h2><p>リッチエディタのフォーマットを<strong>変更</strong>できるようになりました。<br><br><img src=\"https://images.microcms-assets.io/assets/9f54a34e853e4bee98b47ce18c0713f1/c22bcc0296204e81889119c2ffa9a883/domenico-loia-hGV2TfOh0ns-unsplash.jpg\" alt=\"\"><br></p>",
}richEditorFormatに object を指定するとオブジェクト型で取得できます。
{
"title": "更新情報",
"content": {
"contents": [
{
"type": "block",
"value": [
{
"type": "text",
"value": "Hello World",
"attributes": {}
}
],
"attributes": {
"header": 2
}
},
{
"type": "textBlock",
"value": [
{
"type": "text",
"value": "リッチエディタのフォーマットを",
"attributes": {}
},
{
"type": "text",
"value": "変更",
"attributes": {
"bold": true
}
},
{
"type": "text",
"value": "できるようになりました。",
"attributes": {}
},
{
"type": "text",
"value": "\n",
"attributes": {}
},
{
"type": "text",
"value": "\n",
"attributes": {}
}
]
},
{
"type": "image",
"value": "https://images.microcms-assets.io/assets/9f54a34e853e4bee98b47ce18c0713f1/c22bcc0296204e81889119c2ffa9a883/domenico-loia-hGV2TfOh0ns-unsplash.jpg",
"attributes": {
"link": null,
"target": null,
"alt": null,
"width": 640,
"height": 427
}
},
]
},
}既知の不具合として、richEditorFormatに object を指定した際に、リスト形式をネストして利用している箇所が、レスポンスに含まれない事象を確認しています。恐れ入りますが、ご利用にあたっては、あらかじめご了承いただけますと幸いです。
レスポンスの例です。
{
"contents": [
{
"id": "ywsd1lc_z",
"createdAt": "2022-04-27T02:44:50.280Z",
"updatedAt": "2022-04-27T02:44:50.280Z",
"publishedAt": "2022-04-27T02:44:50.280Z",
"revisedAt": "2022-04-27T02:44:50.280Z",
"name": "更新情報"
},
{
"id": "t9xe_ys44",
"createdAt": "2022-04-27T02:44:50.197Z",
"updatedAt": "2022-04-27T02:44:50.197Z",
"publishedAt": "2022-04-27T02:44:50.197Z",
"revisedAt": "2022-04-27T02:44:50.197Z",
"name": "チュートリアル"
},
{
"id": "4sqeq8g36n8",
"createdAt": "2022-04-27T02:44:50.068Z",
"updatedAt": "2022-04-27T02:44:50.068Z",
"publishedAt": "2022-04-27T02:44:50.068Z",
"revisedAt": "2022-04-27T02:44:50.068Z",
"name": "テクノロジー"
}
],
"totalCount": 3,
"offset": 0,
"limit": 10
}
取得したAPIの値は contents という配列で返されます。それに加え以下の値がレスポンスに含まれます。
APIに含まれるコンテンツの総数です。filtersパラメータ / qパラメータを利用したリクエストの場合のみ、条件に合致するコンテンツの件数となります。
指定された取得件数の値です。
デフォルト値は10です。
指定された取得開始位置のオフセットの値です。
デフォルト値は0です。
一部のレスポンスヘッダのみ記載しています。記載の項目以外にも付与される項目がありますので、ご注意ください。
レスポンス時のサーバーサイドの時刻の値です。フォーマットはISO 8601です。
x-current-date-time: 2023-01-01T00:00:00.000ZコンテンツAPIのエラーレスポンスを参照ください。