Use GRAPHQL API

GraphQL APIの使用

コマンドラインからGraphQLオペレーションを発見・構築・実行・連鎖させます。

使用タイミング

• GraphQLエンドポイント（GitHub、Hasura、Apolloなど）経由でデータを照会・更新するとき
• GraphQLを必要とするGitHubオペレーション（Discussions、Projects v2）を自動化するとき
• GraphQL APIから構造化データを取得するシェルスクリプトを構築するとき
• 1つのオペレーションの出力を次のオペレーションへの入力として使う複数のGraphQL呼び出しを連鎖させるとき

入力

• 必須: GraphQLエンドポイントURLまたはサービス名（例：github）
• 必須: オペレーションの意図（読み取りまたは書き込みするデータ）
• オプション: 認証トークンまたは方式（デフォルト：GitHubにはgh CLI認証）
• オプション: 出力フォーマットの選択（生JSON、jqフィルター済み、変数代入）

手順

ステップ1: スキーマの発見

利用可能な型、フィールド、クエリ、ミューテーションを確認します。

GitHubの場合：

# List available query fields
gh api graphql -f query='{ __schema { queryType { fields { name description } } } }' \
  | jq '.data.__schema.queryType.fields[] | {name, description}'

# List available mutation fields
gh api graphql -f query='{ __schema { mutationType { fields { name description } } } }' \
  | jq '.data.__schema.mutationType.fields[] | {name, description}'

# Inspect a specific type
gh api graphql -f query='{
  __type(name: "Repository") {
    fields { name type { name kind ofType { name } } }
  }
}' | jq '.data.__type.fields[] | {name, type: .type.name // .type.ofType.name}'

汎用エンドポイントの場合：

# Full introspection query via curl
curl -s -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  | jq '.data.__schema.types[] | select(.kind == "OBJECT") | {name, fields: [.fields[].name]}'

期待結果： 利用可能な型、フィールド、またはミューテーションを一覧表示するJSON出力。スキーマレスポンスがエンドポイントに到達可能で認証トークンが有効であることを確認します。

失敗時：

• 401 Unauthorized — トークンを確認してください。GitHubの場合はgh auth statusを実行
• Cannot query field — エンドポイントがイントロスペクションを無効にしている可能性があります。代わりにドキュメントを参照してください
• 接続拒否 — エンドポイントURLとネットワークアクセスを確認してください

ステップ2: オペレーションタイプの特定

タスクにクエリ（読み取り）、ミューテーション（書き込み）、またはサブスクリプション（ストリーム）が必要かどうかを判断します。

GitHub固有のオペレーションについては、GitHub GraphQL API docsを参照してください。

# Quick check: does the mutation exist?
gh api graphql -f query='{ __schema { mutationType { fields { name } } } }' \
  | jq '.data.__schema.mutationType.fields[].name' | grep -i "discussion"

期待結果： クエリとミューテーションのどちらが必要かが明確になり、正確なオペレーション名（例：createDiscussion、repository）が特定されます。

失敗時：

• オペレーションが見つからない — より広い用語で検索するか、APIバージョンを確認してください
• クエリとミューテーションの区別が不明 — アクションが状態を変更する場合はミューテーションです

ステップ3: オペレーションの構築

フィールド、引数、変数を使ってGraphQLクエリまたはミューテーションを構築します。

クエリの例 — リポジトリのディスカッションカテゴリを取得：

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 10) {
        nodes { id name }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" | jq '.data.repository.discussionCategories.nodes'

ミューテーションの例 — GitHubディスカッションの作成：

gh api graphql -f query='
  mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repoId,
      categoryId: $categoryId,
      title: $title,
      body: $body
    }) {
      discussion { url number }
    }
  }
' -f repoId="$REPO_ID" -f categoryId="$CAT_ID" \
  -f title="My Discussion" -f body="Discussion body here"

主要な構築ルール：

1. 再利用性のために、インライン値ではなく常に変数（$var: Type!）を使用する
2. レスポンスサイズを最小化するために必要なフィールドのみリクエストする
3. ページネーション付きコネクションにはfirst: Nとnodesを使用する
4. すべてのオブジェクト選択にidを追加する — 連鎖に必要になる

期待結果： 適切な変数、フィールド選択、ページネーションパラメータを持つ構文的に有効なGraphQLオペレーション。

失敗時：

• 構文エラー — ブラケットの対応とトレーリングカンマを確認してください（GraphQLにはトレーリングカンマがない）
• 型の不一致 — スキーマに対して変数の型を確認してください（例：ID!対String!）
• 必須フィールドの欠落 — スキーマに従って必須入力フィールドを追加してください

ステップ4: CLIによる実行

オペレーションを実行してレスポンスをキャプチャします。

GitHub — gh api graphqlの使用：

# Simple query
gh api graphql -f query='{ viewer { login } }'

# With variables
gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id name }
  }' \
  -f owner="octocat" -f repo="Hello-World"

# With jq post-processing
REPO_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id }
  }' \
  -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.id')

汎用エンドポイント — curlの使用：

curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "$(jq -n \
    --arg query 'query { users { id name } }' \
    '{query: $query}'
  )"

期待結果： リクエストされたフィールドを含むdataキーを持つJSONレスポンス。オペレーションが失敗した場合はerrors配列。

失敗時：

• レスポンスにerrors配列 — メッセージを読んでください。よくある原因：権限の欠落、無効なID、レート制限
• 空のdata — クエリがレコードと一致しなかった。入力値を確認してください
• HTTP 403 — トークンに必要なスコープがない。GitHubの場合はgh auth statusを確認し、gh auth refresh -s scopeでスコープを追加してください

ステップ5: レスポンスの解析

JSONレスポンスから必要なデータを抽出します。

# Extract a single value
gh api graphql -f query='{ viewer { login } }' --jq '.data.viewer.login'

# Extract from a list
gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      issues(first: 5, states: OPEN) {
        nodes { number title }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.issues.nodes[] | "\(.number): \(.title)"'

# Assign to a variable for later use
CATEGORY_ID=$(gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 20) {
        nodes { id name }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.discussionCategories.nodes[] | select(.name == "Show and Tell") | .id')

期待結果： 表示またはシェル変数への代入に対応したクリーンで抽出された値。

失敗時：

• jqがnullを返す — フィールドパスが間違っています。まず生のJSONをjq .にパイプして構造を確認してください
• 1つを期待しているときに複数の値 — select()フィルターまたは| firstを追加してください
• Unicode問題 — 生の文字列出力のために-rフラグをjqに追加してください

ステップ6: オペレーションの連鎖

1つのオペレーションの出力を次のオペレーションへの入力として使用します。

# Step A: Get the repository ID
REPO_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id }
  }' \
  -f owner="$OWNER" -f repo="$REPO" \
  --jq '.data.repository.id')

# Step B: Get the discussion category ID
CAT_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 20) {
        nodes { id name }
      }
    }
  }' \
  -f owner="$OWNER" -f repo="$REPO" \
  --jq '.data.repository.discussionCategories.nodes[]
    | select(.name == "Show and Tell") | .id')

# Step C: Create the discussion using both IDs
RESULT=$(gh api graphql \
  -f query='mutation($repoId: ID!, $catId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repoId,
      categoryId: $catId,
      title: $title,
      body: $body
    }) {
      discussion { url number }
    }
  }' \
  -f repoId="$REPO_ID" -f catId="$CAT_ID" \
  -f title="$TITLE" -f body="$BODY" \
  --jq '.data.createDiscussion.discussion')

echo "Created: $(echo "$RESULT" | jq -r '.url')"

パターン： IDフィールドを前のクエリで常に抽出し、後続のミューテーションにID!変数として渡せるようにしてください。

期待結果： 各呼び出しが成功し、IDがオペレーション間で正しく流れる複数ステップのワークフロー。

失敗時：

• 変数が空 — 前のステップがサイレントに失敗した。set -eを追加して各中間値を確認してください
• IDフォーマットが間違い — GitHubのノードIDは不透明な文字列（例：R_kgDO...）です。手動で構築しないでください
• レート制限 — 呼び出し間にsleep 1を追加するか、エイリアスを使ってクエリをバッチ処理してください

バリデーション

1. イントロスペクションクエリがスキーマデータを返す（ステップ1が成功）
2. 構築されたクエリが構文的に有効（GraphQLパーサーエラーなし）
3. レスポンスにerrorsなしでdataキーが含まれる
4. 抽出された値が期待される型と一致する（IDは空でない文字列、カウントは数値）
5. 連鎖されたオペレーションがエンドツーエンドで完了する（ミューテーションが前のクエリのIDを使用）

よくある落とし穴

関連スキル

• scaffold-nextjs-app — GraphQL APIを使用するWebアプリのスキャフォールド
• create-pull-request — GitHubワークフローの自動化（RESTベースの対応物）
• manage-git-branches — API自動化と組み合わせることが多いGitオペレーション
• serialize-data-formats — レスポンス処理で使用するJSONパースパターン