レスポンスの値

コンテンツのフィールドは、レスポンス直下にフィールドIDをキーとして返ります。管理画面で保存する内部データの形とは異なる場合があるため、サイト側では配信APIの形を使ってください。

自動で付く情報

日時はISO 8601の文字列です。アプリの表示時に必要なタイムゾーンへ変換します。fieldsを指定した場合は、id以外のメタ情報も選択対象です。

publishedAtは最終更新日時ではありません。更新の表示にはupdatedAtを使ってください。ステータスやdraftKeyは、通常の配信コンテンツのメタ情報には含まれません。

多言語のAPIでは、createdAt・updatedAt・publishedAtも実際に返した言語版の日時です。include=_langsを指定したときだけ、追加の_langsが付きます。

{ "_langs": { "current": "en", "available": ["ja", "en"] } }

currentはフォールバックした場合、要求した言語ではなく実際に返したメイン言語になります。availableは公開中の言語だけです。詳しくは多言語の配信を参照してください。

文字列・数値・選択肢

任意の項目や過去のスキーマで作成した記事には値がない場合があります。型定義があっても、未入力のケースを考慮してください。

画像とファイル

{  "eyecatch": {    "url": "https://media.genko.me/example/image.webp",    "alt": "ノートに原稿を書く様子"  },  "gallery": [    { "url": "https://media.genko.me/example/detail.webp", "alt": "ノートの詳細" }  ],  "document": "https://media.genko.me/example/document.pdf"}

上記のURLは形を示す例です。実際のURLはレスポンスから取得してください。画像はurlとalt、複数画像はその配列、ファイルはURL文字列です。内部メディアIDは配信値に含まれません。

リッチテキスト内の画像も、配信時にimg要素のURLへ解決されます。差し替えへ追従するため、保存しておいた古いURLを使い続けず、コンテンツを再取得します。

コンテンツ参照

参照の形はdepthによって変わります。展開後は通常のコンテンツと同じく、idと各フィールド、日時を持つオブジェクトです。展開時に非公開の参照先は単一参照でnull、複数参照で配列から除外されます。depth=0や参照先APIがキーの対象外の場合はIDのままです。

参照先の種類を自動で推論するわけではありません。CLIの生成型は単一参照がunknown、複数参照がunknown[]です。参照の展開条件と、API設定がない場合の扱いはクエリ仕様を確認してください。

連携ブロック

保存されたプロバイダー別の値に、生成できる場合のみembedUrlを追加します。Google Maps、YouTube、Figma、CodePen、CodeSandboxでは埋め込み用URLを返します。対応サービスと入力方法は連携ブロックを参照してください。

embedUrlは常にあるとは限りません。 Google Drive、Dropbox、Xなど生成対象でない場合は、このキー自体が省略されます。値が文字列か確認してからiframeへ渡し、ない場合はプロバイダーに応じた表示にしてください。Dropboxの値には公開共有URLが含まれません。

型と実データ

SDKは取得したJSONを、指定されたTypeScriptの型として返します。レスポンス全体を実行時に検証する機能ではありません。

特にfieldsでの項目削減、depthでの参照の形の変更、任意フィールドは、型だけでは実データの存在を保証できません。必要に応じてアプリ側で値を検証します。