Oracle Content ManagementでのGraphQLサポート

17 Oracle Content ManagementでのGraphQLサポート

Oracle Content Managementには、公開されたすべてのコンテンツおよびすべてのアセット・タイプに対するGraphQLのサポートが含まれます。開発者は、スキーマを検査し、問合せを作成して、それらをクライアントから他の配信APIと同時に呼び出すことができます。

GraphQLは、クライアントがリクエストするコンテンツのみを取得することに重点を置いたコンテンツにアクセスするための、既知の問合せ言語です。 GraphQLは、APIを柔軟かつ開発者が使いやすいように設計されています。この柔軟性と機能性をサポートするために、GraphQLには、開発者が直感的な方法で問合せを作成できる、完全で予測可能なスキーマが含まれます。詳細は、https://graphql.org/およびhttps://spec.graphql.org/October2021/を参照してください

次の項では、Oracle Content ManagementでGraphQLを操作する方法について説明します:

GraphQLの開始

最速の方法は、スキーマを検索していくつかの問合せを試行することです。 Oracle Content Managementには、スキーマの探索と問合せの実行に役立つGraphQL IDEが含まれています。

スキーマの検索

GraphQL IDEは、http:// your_instance /content/published/api/v1.1/graphql/explorerにあります。

ドキュメント・エクスプローラ(右上)で、名前を使用してアセット・タイプを検索し、そのタイプのスキーマを表示します。次のイメージは、PressReleaseという名前のアセット・タイプを示しています。 Oracle Content Managementのすべてのアセット・タイプは、同じ名前のGraphQLタイプで表されます(いくつかの便利なネーミング規則変換を適用します)。アセット・タイプ内のすべてのフィールドは、同等のデータ型を持つGraphQLフィールドで表されます。

タイプ名をクリックして関連タイプの詳細を表示します。たとえば、PressReleaseのすべてのユーザー定義フィールドは、pressReleaseFieldsタイプ(前述のスキーマの最後のエントリ)にあります。次のイメージは、pressReleaseFieldsをクリックした後に表示される詳細を示しています。

一部の問合せを試す

GraphQLは、問合せを介してコンテンツにアクセスできます。この項の問合せは、「GraphQL問合せ」および「GraphQLサンプル」で例として使用します。

コンテンツ問合せを実行するには、いくつかの公開済コンテンツ・アイテムのID (またはスラグ)と公開チャネルのchannelTokenが必要です。左側のパネルで問合せを入力し、をクリックします。

次の例では、次のパラメータを使用して問合せを実行します:

アセット・タイプ: PressRelease
コンテンツ・アイテムID: CORE1FADA80EEACE4B4A84B76C07A931B317
チャネル・トークンの公開: 573ae0bcb95347d283cdbea8a4d29641

{
  getPressRelease(id: "CORE1FADA80EEACE4B4A84B76C07A931B317",
                  channelToken: "573ae0bcb95347d283cdbea8a4d29641") {
    id
    name
    description
  }
}

問合せの実行後、次が表示されます。

ユーザー定義フィールド、他のアセットへの参照など、追加のフィールドを問合せに含めることができます。 IDEは、フィールド名を自動的に入力することで問合せを支援します。

GraphQLスキーマ

GraphQL問合せは、コンテンツのスキーマまたはデータ・モデルに対して機能します。 Oracle Content Managementでは、GraphQLスキーマを作成する必要はありません。Oracle Content Managementのすべてのアセット・タイプはスキーマに自動的に表されます。 GraphQLタイプ名は、Oracle Content Managementのアセット・タイプのAPI名に基づいており、GraphQLの予約語との競合や競合を回避するために必要なプレフィクスが付いています。

PressReleaseアセット・タイプのスキーマの詳細を確認します。

タイプ、組合およびインタフェース

前述のとおり、PressReleaseアセット・タイプは、pressReleaseとpressReleaseFieldsの2つのGraphQLタイプで表されます。 pressReleaseタイプは、ID、名前、説明などの標準フィールドを含む、PressReleaseアセット・タイプのコア構造を表します。 pressRelease fieldsフィールドで参照されるpressReleaseFieldsタイプには、すべてのユーザー定義フィールドが含まれます。この構造は、REST APIがフィールド・データをどのように表現するかを反映しています。

テキストで説明されているpressReleaseおよびpressReleaseFieldsスキーマ

ユーザー定義フィールド(タイトルや抽象など)に加えて、pressReleaseFieldsタイプには関連するデータ型が含まれます(次のマッピングを参照)。アセット・タイプでフィールドが必須として設定されている場合、GraphQLスキーマではこれらのフィールドが必須として表示されます(title: String!など)。フィールドが参照フィールド(参照またはメディア)の場合、GraphQLスキーマはターゲット・コア・アセット・タイプを参照します。たとえば、authorフィールドはpressReleaseAuthorアセット・タイプを参照します。

Oracle Content Managementの参照フィールドは、複数のタイプを受け入れることができます。このようなシナリオでは、このような参照を表すためにGraphQL結合タイプが定義されます。たとえば、「マスト・ヘッド」フィールドはunionAllMediaTypesで宣言されます。

pressReleaseタイプがアイテムを実装していることに注意してください。これはインタフェース・アイテムです。インタフェース・アイテム(下記参照)は、GraphQLのすべてのコア・アセット・タイプのベースです。また、タクソノミ(タクソノミフィールド)および翻訳(変数および変動フィールド)へのアクセスも含まれます。これについては、後で詳しく説明します。

次の表に、品目インタフェース・フィールドを示します。

スキーマ・アイテム
id:	ID!
name:	String!
タイプ:	String!
typeCategory:	文字列
スラグ:	文字列
language:	文字列
翻訳可能:	ブール!
説明:	文字列
createdDate:	DateTime!
updatedDate:	DateTime!
variation(variationType: String!, variationName: String):	item
variations(variationType: String!):	[item]
分類:	[taxonomy]

データ型

Oracle Content Managementデータ型は同等のGraphQLタイプ(必要に応じて適切なネイティブ・タイプおよびスカラー)にマップされます。 DateTimeおよびJSONは、スキーマに自動的に含まれます。

Oracle Content Managementデータ型	GraphQLフィールド・タイプ
Boolean	Boolean
日付	DateTime
Decimal	Float
JSON	JSON
大きいテキスト	文字列
メディア	ターゲット・アセット・タイプまたは組合
数値	Int
リファレンス	ターゲット・アセット・タイプまたは組合
テキスト	文字列

これらのデータ型に加えて、各アセットのOracle Content Management IDは、GraphQLのIDフィールド・タイプにマップされます。

GraphQL問合せ

Oracle Content Managementは、アセットにアクセスするための問合せを自動的に生成します。汎用アイテム問合せ(getItem(..))があり、各コア・アセット・タイプは対応する問合せを取得します(たとえば、getPressRelease(..))。

前述のとおり、左側のパネルに問合せを入力し、The IDEをクリックすると、問合せを記述しやすくなりますが、アイテムの取得に使用する基本的な書式で、イタリック体のテキストを適切な値に置き換えます。問合せに引数として、またはHTTPリクエストのヘッダーとして、channelTokenを含める必要があります。アセットのIDまたはスラグを含める必要があります。

{
    getItem(channelToken: channel_token, id: ID, slug: slug): item
}

または

{
    getPressRelease(channelToken: channel_token, id: ID, slug: slug): pressRelease
}

GraphQLでは、単一のアセットをフェッチする問合せに加えて、フィルタリング基準およびソート順序に基づいて、多数のアセットをまとめてフェッチすることもできます。そのためには、即時利用可能な問合せがスキーマに含まれます。

{
	getItems(channelToken: String, 
filter: standardFilter, 
query: queryFilter, 
sort: [standardSort], 
limit: int, offset: int) : itemCollection
}

この機能をサポートするために、いくつかの標準タイプが導入されています:

standardFilterでは、アセットのフィルタリング基準の作成がサポートされています。
queryFilterでは、多数のフィールドの検索がサポートされています。
standardSortは、フィールド値に基づいてソート順序結果を指定します。
limit and offsetは、クライアントが結果をページングするための手段を提供します。

この問合せの結果自体は、他のアイテムのコレクションであるitemCollectionであり、これがページ区切りの詳細とともにアイテム配列を持っています。

standardFilterタイプは、スキーマに入力タイプとして定義されます。

standardFilterタイプ

次の表に、standardFilterフィールドを示します。

アイテムstandardFilter
id:	idFilter
name:	stringFilter
説明:	stringFilter
タイプ:	stringFilter
typeCategory:	stringFilter
カテゴリ:	assetCategoryFilter
スラグ:	stringFilter
language:	stringFilter
翻訳可能:	booleanFilter
createdDate:	dateTimeFilter
updatedDate:	dateTimeFilter
AND:	[standardFilter]
または:	[standardFilter]
NOT:	standardFilter

このタイプのフィールド名は、アイテムのOracle Content Managementの標準フィールドの名前と同じです。これらのフィールドで使用できる値は、stringFilter、idFilterなどの入力タイプです。これらの入力タイプは、操作と値のタプルを表すフィールドの基礎となるデータ型に固有です。 stringFilterタイプは下に展開され、このタプルのシェイプが表示されます。

stringFilterおよびstringFilterOpsタイプ

これらのデータ型固有の入力フィールドでは、問合せにデータ型の有効な基準のみを含めることができます。詳細は、「GraphQLデータ型および使用可能な操作表」を参照してください。

GraphQLでは、standardFilterタイプを使用する汎用アイテム問合せ(getItems(..))に加えて、タイプ固有のフィールドを指定できる型固有の問合せもサポートされます。これを行うには、Oracle Content Managementで定義されているアセット・タイプごとに、付属のタイプ固有のフィルタが含まれます。 PressReleaseアセット・タイプの例を続けると、そのフィルタは次のように表されます:

PressReleaseFieldsFilterタイプ

standardFilterタイプに存在するすべてのフィールドは、pressReleaseFilterタイプでも使用できることに注意してください。つまり、standardFilterタイプで可能な問合せは、タイプ固有のフィルタを使用して作成することもできますが、ユーザー定義のフィールド固有のフィルタを指定することもできます。 standardFilterタイプと同様に、AND、ORおよびNOTを使用して、タイプ固有のフィルタを組み合せることができます。

また、タイプ固有のフィールドには、すべてのユーザー定義フィールドをリストする別の入力タイプを参照するfieldsというフィールドが含まれています。

GraphQLスキーマでは、アイテム・コンテンツの取得に加えて、次の問合せを使用した公開済タクソノミ情報の取得もサポートされています。

{
	getTaxonomy(channelToken: String, id: ID): taxonomy
}

および

{
	getTaxonomies(channelToken: String, sort: [taxonomySort]) : taxonomyCollection
}

カテゴリは、次の問合せを使用して、タクソノミからフェッチすることも、直接フェッチすることもできます。

{
	getCategory(id: ID, taxonomyId: ID, channelToken: String, apiName: String): category
}

{
	getCategories(id: ID, taxonomyId: ID, channelToken: String, limit: int, offset: int): categoryCollection
}

例

アセットを取得: 標準フィールドによるアセットのフィルタおよびソート

標準フィールド(name, id, description, typeなど)を使用したフィルタによるアセットの取得は、standardFilterを使用して行います。たとえば、特定のタイプのアセットの取得は、タイプ・フィールドの値に基づいた条件を使用してstandardFilterによって行われます。

{ getItems(channelToken: "573ae0bcb95347d283cdbea8a4d29641", filter: {type: {op: EQUALS, value: "MyType"}}) { totalResults items { id name description } }}

standardFilterにOR条件を作成することで、複数のタイプのアセットを簡単に取得できます。

{
  getItems(channelToken: "573ae0bcb95347d283cdbea8a4d29641", 
    filter: { 
            OR: [
                {type: {op: EQUALS, value: "myType1"}}, 
                {type: {op: EQUALS, value: "myType2"}}
                ] 				}
  ) 
  
  {
    totalResults
    items {
      id
      name
      description
    }

Item(品目)インタフェースに存在する標準フィールドでは、フィルタリングが可能です。各フィールドには、データ型に応じて様々な操作(EQUALSやNOT_EQUALSなど)が用意されています。各データ型で使用可能な操作については、次の表を参照してください。

クライアントは、フィルタリングに加えて、問合せのソート基準を指定できます。次の例では、nameフィールドの値によって結果をソートします。

{
  getItems(channelToken: "573ae0bcb95347d283cdbea8a4d29641", 
    filter: {type: {op: EQUALS, value: "MyType"}}
    sort: {name :DESC}
  ) {
    totalResults
    items {
      id
      name
      description
    }
  }
}

フィルタリングおよびソートに加えて、クライアントはlimitおよびoffsetを使用してページ区切り指示を指定できます。次の例は、クライアントが最初の20 (オフセット)の後に最大10の結果(制限)をフェッチする方法を示しています。

{
  getItems(channelToken: "573ae0bcb95347d283cdbea8a4d29641", 
    filter: {type: {op: EQUALS, value: "myType"}}
    sort: {name :DESC}
    limit: 10
    offset: 20
  ) {
    totalResults
    count
    items {
      id
      name
      description
    }
  }
}

タイプ固有のフィルタの指定による特定タイプのアセットの取得

次の例のフィルタリング基準には、ユーザー定義のフィールド・タイトルと、タイトル・フィールドにOracleを含むすべてのPressReleaseアセットに対する問合せが含まれます。

{
  getPressReleaseCollection(channelToken: "573ae0bcb95347d283cdbea8a4d29641", 
    filter: {fields: {title: {op: CONTAINS, value: "Oracle"}}}) {
    items {
      name
      id
    }
  }
}

フィルタと同様に、タイプ固有のフィルタはネストできます。

{
  getPressReleaseCollection(channelToken: "573ae0bcb95347d283cdbea8a4d29641", 
    filter: {fields: {title: {op: CONTAINS, value: "Oracle"}}, AND: {language: {op: EQUALS, value: "en-US"}}}) {
    items {
      name
      id
      language
      fields {
        title
      }
    }
  }
}

タクソノミおよびカテゴリ情報の取得

単一のアセット取得と同様に、getTaxonomyを使用してタクソノミを取得できます。次の例は、公開されたタクソノミと、最初の3レベルのカテゴリ情報を取得する方法を示しています。

{
  getTaxonomy(channelToken: "573ae0bcb95347d283cdbea8a4d29641", id: "F95CD0EB0E02427C9A3B7F1B8F33645C") {
    id
    name
    categories {
      id
      name
      children {
        id
        name
        children {
          id
          name
        }
      }
    }
  }
}

同様に、getTaxonomiesを使用して、公開されたすべてのタクソノミを取得できます。次の例は、各カテゴリの下に最初の3レベルのカテゴリがあるすべての公開済タクソノミを取得する方法を示しています。

{
  getTaxonomies(channelToken: "573ae0bcb95347d283cdbea8a4d29641") {
    taxonomies {
      id
      name
      categories {
        id
        name
        children {
          id
          name
          children {
            id
            name
          }
        }
      }
    }
  }
}

カテゴリ自体をリストしたり、id/apiNameによってフェッチしたりできます。次の例は、apiNameでカテゴリをフェッチし、その子を2レベル下へフェッチする方法を示しています。

{
getCategory(channelToken:"573ae0bcb95347d283cdbea8a4d29641", taxonomyId: "F95CD0EB0E02427C9A3B7F1B8F33645C" apiName:"hk-p")
  {
    name
    id
    apiName
    children {
      name
      id
      apiName
    }
  }
}

GraphQLデータ型と使用可能な操作

値

文字列

EQUALS

NOT_EQUALS

CONTAINS

NOT_CONTAINS

STARTS_WITH

MATCH

SIMILAR

DateTime

EQUALS

NOT_EQUALS

BEFORE

AFTER

BEFORE_OR_EQUAL

AFTER_OR_EQUAL

Boolean

(操作なし、true/falseのみ)

内部および浮動

EQUALS、NOT_EQUALS、

GREATER_THAN

GraphQLコンテンツ・プレビューのサポート

GraphQLでは、コンテンツ・プレビューREST APIと同様の未公開コンテンツの問合せがサポートされています。「Content PreviewのREST API」を参照してください。

チャネルに公開またはチャネルにターゲット指定されているコンテンツは、GraphQLのコンテンツ・プレビューAPIを介して利用できます。 GraphQLプレビューでは、アセットの最新バージョンにアクセスできます。

プレビュー・コンテキストのアセットにアクセスするには、GraphQLエンドポイントはhttp://user_instance/content/preview/api/v1.1/graphqlにあり、GraphQL IDEはhttp://user_instance/content/preview/api/v1.1/graphql/explorerにあります。

GraphQLでアセットをプレビューするには、ユーザー認証が必要です。「Content PreviewのREST API」の「認可」を参照してください。

公開されたアセットで使用可能なすべてのGraphQL機能(問合せおよびスキーマ)もプレビューで使用できます。

GraphQLサンプル

IDまたはスラグを使用したアセット・データの取得

次の問合せでは、アセットIDを使用してアセット・データを取得します。

{
  getPressRelease(channelToken: "573ae0bcb95347d283cdbea8a4d29641", id: "CORE1FADA80EEACE4B4A84B76C07A931B317")
  {
    id
    fields {
      title
      abstract
      body
    }
  }
}

次の問合せでは、IDのかわりにslugを使用して前述の問合せと同じ結果が生成されます。

{
  getPressRelease(channelToken: "573ae0bcb95347d283cdbea8a4d29641", slug: "bed-bath-beyond-selects-oracle-to-modernize-enterprise")
  {
    id
    fields {
      title
      abstract
      body
    }
  }
}

参照アセット・データの取得

次の問合せでは、参照作成者タイプのフィールドとpressReleaseフィールドが取得されます。

{
  getPressRelease(channelToken: "573ae0bcb95347d283cdbea8a4d29641", slug: "bed-bath-beyond-selects-oracle-to-modernize-enterprise") {
    id
    fields {
      title
      abstract
      body
      author {
        fields {
          firstname
          lastname
          bio
        }
      }
    }
  }
}

デジタル・アセットのレンディションの取得

renditionというデフォルト・タイプが、様々なメディア・レンディションを表すスキーマに含まれています。レンディションのURLに簡単にアクセスできるようになり、コードに簡単に含めることができます。たとえば、次の問合せでは、イメージの大きなレンディションが返されます。

{
  getPressRelease(channelToken: "573ae0bcb95347d283cdbea8a4d29641", slug: "bed-bath-beyond-selects-oracle-to-modernize-enterprise") {
    id
    fields {
      title
      abstract
      body
      masthead {
        ...headerImage
      }
    }
  }
}
  fragment headerImage on image {
  id
  fields {
    rendition(name: "Large", format: "jpg") {
      file {
        url
      }
    }
  }
}

特定のレンディションを取得するかわりに、「レンディション」パラメータを使用して、レンディションのリスト(jpg形式とwebp形式の両方を含む)を取得できます。

{
  getPressRelease(channelToken: "573ae0bcb95347d283cdbea8a4d29641", slug: "bed-bath-beyond-selects-oracle-to-modernize-enterprise") {
    id
    fields {
      title
      abstract
      body
      masthead {
        ...headerImages
      }
    }
  }
}
  fragment headerImages on image {
  id
  fields {
    renditions {
      file {
        url
      }
    }
  }
}