重要

このページの日本語コンテンツは古くなっている可能性があります。最新の英語版コンテンツをご覧になるには、こちらをクリックしてください。

重要

この機能はプレビュー機能として利用できます。プレビュー機能とは、開発者から早い段階でフィードバックを受けるために提供している Confluent Cloud のコンポーネントのことです。この機能は、評価用、本稼働環境以外でのテスト用、あるいは Confluent にフィードバックを提供するために使用できます。ご意見、ご質問、ご提案は stream-governance-preview@confluent.io までお寄せください。

ストリームカタログの GraphQL API¶

ストリームカタログは内部で GraphQL を利用するだけでなく、デプロイで使用できるストリームカタログの GraphQL API も公開しています。

スタートガイド¶

Confluent ストリームカタログは、環境内のスキーマとその他のメタデータエンティティ、さらにそれらの間の関係を保存する一元的なリポジトリを提供します。1 つまたは複数の関連メタデータエンティティに対してクエリを実行する場合、GraphQL を使用して 1 つの応答でリクエストされたメタデータエンティティすべてを返すことができます。

ストリームカタログの GraphQL API はクエリのみをサポートする読み取り専用 API であり、変更やサブスクリプションはサポートしません。

GraphQL エンドポイント¶

ストリームカタログの GraphQL エンドポイントは https://<SR ENDPOINT>/catalog/graphql です。このエンドポイントは、GraphQL 実装の推奨手法で説明されているように、POST リクエストと GET リクエストの両方をサポートします。

GraphQL スキーマ¶

GraphQL スキーマに対して、任意の数の GraphQL ツールを使用してイントロスペクションを実行できます。このスキーマはこちらでも確認できます。

エンティティのクエリ¶

エンティティのフェッチリスト¶

単純なクエリを使用して、同じタイプの単独のエンティティまたは複数のエンティティをフェッチできます。

例: フィールドのリストをフェッチする。

query {
  sr_field {
    name
  }
}

関係を使用したネスト化されたエンティティのフェッチ¶

必要な関係を指定することで、単独のエンティティとその関連エンティティをフェッチできます。

例: フィールドのリストと、各フィールドの record、schema、subject_version の名前をフェッチする。

query {
  sr_field {
    name
    record {
      name
      schema {
        name
        subject_versions {
          name
        }
      }
    }
  }
}

例: subject_version エンティティのリストと、対応するスキーマの各フィールドの名前をフェッチする。

ちなみに

スキーマにはレコードに加えて複数のタイプを含めることができるため、この例では sr_record のタイプ条件を含むインラインフラグメントを使用しています。

query {
  sr_subject_version(where: {name: {_starts_with: "my_subject"}}) {
    name
    schema {
      id
      types {
          ... on sr_record {
          name
          fields {
            name
          }
        }
      }
    }
  }
}

"where" 引数を使用したフィルタリング¶

where 引数を使用すると、エンティティの属性の一部に基づいて結果をフィルタリングできます。_and/_or 演算子を使用してフィルターを結合できます。

例: 名前が "field1" のフィールドをフェッチする。

query {
  sr_field(where: {name: {_eq: "field1"}}) {
    name
    createTime
  }
}

例: 名前が "field1" でスキーマ ID が 1 のフィールドをフェッチする。

query {
  sr_field(where: {_and: [{name: {_eq: "field1"}}, {id: {_eq: 1}}]}) {
    name
    createTime
  }
}

where 引数では以下の演算子を使用できます。

_eq
_gt
_lt
_gte
_lte

文字列属性の場合、以下の演算子も使用できます。

_starts_with

日付属性の場合、以下の演算子も使用できます。

_between
_since

例: 特定の期間に作成されたフィールドをフェッチする。

query {
  sr_field(where: {createTime: {_between: {start: "2020-01-01T00:00:00" end: "2022-01-01T00:00:00"}}}) {
    name
    createTime
  }
}

例: 特定の期間以降に作成されたフィールドをフェッチする。

query {
  sr_field(where: {createTime: {_since: last_7_days}}) {
    name
    createTime
  }
}

since パラメーターに指定可能な値:

"order_by" 引数を使用したソート¶

order_by 引数を使用して結果のソートを実行できます。

例: 名前の昇順にフィールドをソートする。

query {
  sr_field(order_by: {name: asc}) {
    name
    createTime
  }
}

order_by 引数で、ソートの方向を asc （昇順）または desc （降順）として指定できます。

"limit" 引数と "offset" 引数を使用したページネーション¶

limit 引数と offset 引数を使用して結果のページネーションを実行できます。

例: 6 番目のフィールドから 5 つのフィールドをフェッチする。

query {
  sr_field(limit: 5, offset: 5) {
    name
    createTime
  }
}

"tags" 引数を使用したタグによるフィルタリング¶

結果に 1 つまたは複数の tags を含めるように指定することで、結果のフィルタリングを実行できます。

例: PII または SECRET がタグ付けされたフィールドをフェッチする。

query {
  sr_field(tags: ["PII", "SECRET"]) {
    name
    createTime
  }
}

"deleted" 引数を使用した削除済みオブジェクトの取り込み¶

通常はアクティブな（削除されていない）エンティティのみが返されます。deleted 引数を true と指定することで、削除済みエンティティも返すことができます。

例: 削除済みのフィールドを含め、すべてのフィールドをフェッチする。

query {
  sr_field(deleted: true) {
    name
    createTime
    status
  }
}

API の制限¶

クエリの制限¶

GraphQL API にはクエリの制限が 2 点あります。

クエリの複雑性の制限: 複雑性の制限とは、クエリ内のデータフィールドの合計数に関する制限です。クエリの複雑性の最大値は 200 です。
クエリの深さの制限: 深さの制限とは、クエリの深さの合計に関する制限です。クエリの深さの最大値は 20 です。

時間の制限¶

GraphQL API には、すべての GraphQL クエリに関して最大 30 秒という時間の制限があります。

レートの制限¶

GraphQL API には、1 秒あたり最大 25 リクエストというレートの制限があります。

API リファレンス¶

ストリームカタログの GraphQL API リファレンスドキュメントを参照してください。