GraphQL ​

GraphQLは、API向けのデータクエリおよび操作言語です。 GraphQLコネクターを使用すると、GraphQL APIをサポートする任意のアプリケーションからレコードをクエリおよび変更できます。

GraphQLコネクターは、アプリケーションスキーマを動的にイントロスペクトして、使用可能なリソースと操作を判断します。 入力フィールドと出力フィールドを自動的に生成します。 これにより、コードを記述せずにWorkato UIでGraphQLクエリとミューテーションを構築できます。

カスタムGraphQLクエリまたはドキュメントが既にある場合は、カスタムアクションを使用できます。 GraphQLコネクターはクエリを解析し、フィールドをスキーマに照らして検証し、対応する入力フィールドと出力フィールドを自動生成します。

GraphQLコネクターを使用するタイミング ​

次の場合にGraphQLコネクターを使用します:

• 統合する予定のアプリケーションがGraphQLエンドポイントを提供している
• そのアプリケーションで使用できるネイティブWorkatoコネクターがない
• RESTエンドポイントを使用せずに、データを柔軟にクエリまたは変更したい

前提条件 ​

GraphQLに接続する前に、次の前提条件を満たしてください:

• Workatoでコミュニティコネクターをインストールし、コネクションを作成するための権限があることを確認します
• コミュニティライブラリからGraphQLコネクターをダウンロード
• 必要な認証情報を取得
• アプリケーションのGraphQLエンドポイントURLを確認します（例: https://api.example.com/graphql）

コミュニティライブラリからGraphQLコネクターをダウンロード ​

次の手順を実行して、コミュニティライブラリからコネクターをインストールします:

必要な認証情報を取得 ​

各GraphQL APIは独自の認証要件を定義します。 アプリケーションのAPIドキュメントを確認して、サポートされている認証方法と、必要な認証情報を取得する方法を判断します。 一般的なオプションは次のとおりです:

WorkatoをOAuthクライアントとして登録 ​

OAuth 2.0コネクションでは、WorkatoをOAuthクライアントとして登録する必要があります。

WorkatoをOAuthクライアントとして登録するには、次の手順を実行します:

資格情報を検証 ​

コネクションを確立する前に、curlやPostmanなどのツールを使用して認証情報をテストし、認証情報が有効であることを確認します。

次のことができる必要があります:

• /graphqlエンドポイントを正常に呼び出す
• 有効なJSONレスポンスを受信する
• アクセストークンを取得する（OAuthコネクションの場合）

コネクション設定 ​

WorkatoでGraphQLコネクションを作成するには、次の手順を実行します:

コネクションに成功すると、Workatoに確認メッセージが表示されます。 コネクションに失敗した場合は、エンドポイントURL、認証の詳細、および権限を確認します。

詳細設定 ​

GraphQLコネクターには、スキーマ内で深くネストされたフィールドの展開方法を制御する2つの詳細オプションがあります:

• スキーマ深度制限（max_schema_depth）: スキーマ内のフィールドの最大ネストレベルを制御します。 デフォルトは5です。
• スキーマ再帰制限（max_recursion_depth）: 無限ループを防ぐため、同じタイプがパス内に出現できる回数を制限します。 デフォルトは5です。

スキーマ設定の調整 ​

Workatoでは、ほとんどのユースケースに適しているデフォルト設定から始めて、その後で調整することをお勧めします。 スキーマ設定を調整するときは、次のプラクティスに従うことをお勧めします:

• 値を高くするとフィールド数が指数関数的に増加する可能性があるため、制限を段階的に増やします
• スキーマごとに動作が異なるため、使用するAPIでこれらの設定をテストします

次の状況でスキーマ設定を調整できます:

制限を増やす場合:

• 深くネストされたデータ構造が必要である
• スキーマに正当なネストレベルが多数ある
• パフォーマンスの問題が発生していない
• デフォルトの深度を超えるフィールドにアクセスする必要がある

制限を減らす場合:

• スキーマ生成が遅すぎる
• UIに表示されるフィールドが多すぎて、移動が困難である
• タイムアウトエラーが発生する
• 最上位または浅いデータ構造のみが必要である

スキーマ例 ​

次の例では、深度制限と再帰制限がスキーマ展開をどのように制御するかを示します。

深度制限の例 ​

深度制限は、コネクターが展開するネストのレベル数を制御します。 ネストされた各オブジェクトによって、深度が1レベル追加されます。

スキーマ例:

type User {
  id: Int
  name: String
  profile: Profile
}

type Profile {
  bio: String
  settings: Settings
}

type Settings {
  theme: String
  preferences: Preferences
}

type Preferences {
  language: String
  advanced: Advanced
}

type Advanced {
  debug: Boolean
}

max_schema_depth = 2の場合:

User (depth 0)
├─ id: Int                    ✓ Included
├─ name: String               ✓ Included
└─ profile: Profile (depth 1)
   ├─ bio: String             ✓ Included
   └─ settings: Settings (depth 2)
      ├─ theme: String        ✓ Included
      └─ preferences (depth 3) ✗ STOPPED - Exceeds depth limit

結果: 深度2レベルまでのフィールドのみが表示されます。

再帰制限の例 ​

再帰制限は、同じ型が1つのパス内に出現できる回数を制御します。 これにより、型が自身を参照する場合や循環依存関係を作成する場合に、無限ループを防ぎます。

循環参照を含むスキーマ例:

type User {
  id: Int
  name: String
  friends: [User]  # Self-reference
  posts: [Post]
}

type Post {
  title: String
  author: User     # References back to User
}

max_recursion_depth = 2の場合:

User (count: 0)
├─ id: Int
├─ name: String
├─ friends: [User] (count: 1)
│  ├─ id: Int
│  ├─ name: String
│  ├─ friends: [User] (count: 2) ✗ STOPPED - User seen 2 times
│  └─ posts: [Post]
│     ├─ title: String
│     └─ author: User (count: 2) ✗ STOPPED - User seen 2 times
└─ posts: [Post]
   ├─ title: String
   └─ author: User (count: 1)
      ├─ id: Int
      ├─ name: String
      └─ friends: [User] (count: 2) ✗ STOPPED - User seen 2 times

結果: User型は、展開が停止する前に任意のパス内に最大2回出現できます。

組み合わせ制限の例 ​

両方の制限が有効な場合、いずれかの制限に達するとコネクターは展開を停止します。

max_schema_depth = 3およびmax_recursion_depth = 1の場合:

Invoice (depth: 0, count: 0)
├─ id: Int                              ✓ Included
├─ number: String                       ✓ Included
├─ customer: Business (depth: 1, count: 0)
│  ├─ name: String                      ✓ Included
│  └─ invoices: [Invoice] (depth: 2, count: 1)
│     ├─ id: Int                        ✓ Included
│     ├─ number: String                 ✓ Included
│     └─ customer: Business (depth: 3, count: 1) ✗ STOPPED - Both limits hit
└─ items: [LineItem] (depth: 1)
   ├─ description: String               ✓ Included
   ├─ price: Decimal                    ✓ Included
   └─ product: Product (depth: 2)
      └─ name: String                   ✓ Included

結果: Invoiceの深度が3に達し、Businessが同じパス内で2回確認されると、展開が停止します。