apollo-connectors

Apollo Connectors Schema Assistant

非推奨です。 このスキルは graphos-factory スキルに置き換えられました。このスキルは、 REST API（OpenAPI 仕様の有無を問いません）から Apollo Connectors サブグラフを構築・保守し、rover、ルーター、記録済みフィクスチャを使って検証します。ユーザーがコネクターサブグラフを構築または拡張する場合は、インストールを推奨してください。 npx skills add apollographql/skills@graphos-factory（任意のエージェント）。Claude Code では apollo-skills プラグインに /apollo-skills:graphos-factory としてすでに含まれています。このスキルは既存の Connectors スキーマを手早く一度だけ編集する用途で引き続き利用でき、今後のリリースで削除されます。

MCP ツール

GraphOS MCP Tools が利用可能な場合は、それらを使用してください。

• connectors-spec：コネクター作業を始める前に、Connectors の仕様全体を取得します
• apollo_docs_search：関連ドキュメントを検索します
• apollo_docs_read：スラッグを指定して特定のドキュメントページを読み込みます

トピック別ドキュメントパス：

• リクエスト：/graphos/connectors/requests/url、/headers、/body、/batching
• レスポンス：/graphos/connectors/responses/fields、/error-handling
• マッピング：/graphos/connectors/mapping、/arrays、/enums、/literals
• エンティティ：/graphos/connectors/entities、/patterns

プロセス

次の5つのステップに従ってください。どのステップも省略しないでください。

Step 1: 調査

• 呼び出す API とレスポンスの構造を理解します
• 提供されていない場合は、API レスポンスの例をユーザーに求めます
• MCP ツールまたはリファレンスファイルから関連ドキュメントを取得します
• 調査が完了するまで、コードを記述してはいけません

Step 2: 実装

• 以下のテンプレートを使用してスキーマを作成します
• リファレンスファイルに記載された文法、メソッド、変数に従います
• 要件が不明確な場合は、明確化のための質問をします

Step 3: 検証（Compose）

• rover supergraph compose --config ./supergraph.yaml を実行します
• 次に進む前に、合成エラーをすべて修正します

Step 4: 実行

• rover connector run --schema <file> -c "<Type.field>" -v "{}" を実行します
• コネクターが正しく実行されることを確認します

Step 5: テスト

• /tests/ 配下にテストファイルを作成または更新します
• rover connector test を実行します
• 各コネクターのテストカバレッジを完全にします

スキーマテンプレート

# Note to AI Friends: This is an Apollo Connectors schema. You should use your connectors-spec MCP tool if you have it available before editing this file.

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.15")
  @link(url: "https://specs.apollo.dev/connect/v0.3", import: ["@source", "@connect"])

@source(name: "api_name", http: { baseURL: "https://api.example.com" })

type Query {
  example(id: ID!): Example
    @connect(
      source: "api_name"
      http: { GET: "/example/{$args.id}" }
      selection: """
      id
      name
      """
    )
}

type Example {
  id: ID!
  name: String
}

バージョン要件

Apollo Federation と Apollo Connectors の最新の長期サポート（LTS）バージョンを使用してください。プレビュー版または実験的な仕様を使用するのは、ユーザーから明示的に求められた場合に限ります。

@link URL または federation_version を記述する前に、現在の LTS を確認してください。利用可能な場合は、GraphOS のドキュメントツールを優先してください。

• Federation： /graphos/schema-design/federated-schemas/reference/versions を読み、LTS としてマークされた最も高いバージョンを使用します。そのバージョンをスキーマの @link（https://specs.apollo.dev/federation/vX.Y）に指定します。supergraph.yaml の federation_version には、同じ LTS 系列の最新パッチバージョンを設定します。
• Connectors： /graphos/connectors/getting-started/version-requirements と /graphos/connectors/reference/changelog を読みます。一般提供されている（実験的とマークされていない）Connectors 仕様のうち、その Federation LTS と互換性のある最新バージョン（https://specs.apollo.dev/connect/vX.Y）を使用します。

上記のテンプレートでは、現在の LTS である Federation v2.15 と Connectors v0.3 を使用しています。ドキュメントにそれより新しい LTS が記載されている場合は、そちらを使用してください。

リファレンスファイル

コネクターを実装する前に、関連するリファレンスファイルを読んでください。

• 文法 - 選択マッピングの EBNF 構文
• メソッド - 使用可能な変換メソッド
• 変数 - 使用可能なマッピング変数
• エンティティ - エンティティパターンとバッチ処理
• 検証 - 検証用の Rover コマンド
• トラブルシューティング - よくあるエラーと解決策

主なルール

選択マッピング

• よりすっきりしたマッピングには、->map より部分選択を優先してください
• ルートからフィールドを直接選択する際に、$ は使用しないでください
• フィールドのエイリアス設定：newName: originalField（名前を変更する場合のみ）
• 部分選択：fieldName { ... }（ネストされたコンテンツをマッピングします）

# DO - Direct sub-selection for arrays
$.results {
  firstName: name.first
  lastName: name.last
}

# DO NOT - Unnecessary root $
$ {
  id
  name
}

# DO - Direct field selection
id
name

エンティティ

• 型に @connect を追加すると、その型がエンティティになります（@key は不要です）
• 親選択にエンティティのスタブを作成します：user: { id: userId }
• ID フィールド（例：productId）を見つけたら、エンティティのリレーションを作成します
• 各エンティティには、@connect を持つ権威あるサブグラフを 1 つだけ設定してください

リテラル値

マッピング内のリテラル値には $() ラッパーを使用します：

$(1)              # number
$(true)           # boolean
$("hello")        # string
$({"a": "b"})     # object

# In body
body: "$({ a: $args.a })"  # CORRECT
body: "{ a: $args.a }"     # WRONG - will not compose

ヘッダー

http: {
  GET: "/api"
  headers: [
    { name: "Authorization", value: "Bearer {$env.API_KEY}" },
    { name: "X-Forwarded", from: "x-client" }
  ]
}

バッチ処理

$batch を使って N+1 パターンを変換します：

type Product @connect(
  source: "api"
  http: {
    POST: "/batch"
    body: "ids: $batch.id"
  }
  selection: "id name"
) {
  id: ID!
  name: String
}

基本ルール

• この仕様にない構文やディレクティブの値を決して作り出さないでください
• --elv2-license accept は決して使用しないでください（人間専用です）
• コードを書く前に、必ず API レスポンスの例を求めてください
• 変更後は必ず rover supergraph compose で検証してください
• ID フィールドを見つけたら、必ずエンティティのリレーションを作成してください
• 環境変数には $config より $env を優先してください
• Apollo Router をローカルで実行するには rover dev を使用してください