platform-api

Platform API 抽出スキル

概要

このスキルでは、Genesys Cloud Platform API の Swagger 2.0 スキーマから API エンドポイント情報を抽出するための jq クエリパターンを提供します。このスキーマは 19MB を超えるファイルで、1,900 を超えるエンドポイントと 4,305 個の定義を含みます。

スキーマ：初回使用前に schema.json をダウンロードする必要があります。このスキルのディレクトリからダウンロードスクリプトを実行してください。

./scripts/download-schema.sh

リージョンのオプションと使い方の詳細については、ダウンロードスクリプトを参照してください。

クエリを実行する前に、この SKILL.md ファイルの親ディレクトリの絶対パスを特定し、スキーマのパス変数を設定してください。

SCHEMA="<resolved-skill-directory>/schema.json"

以下の例では、このファイルを参照するために "$SCHEMA" を使用します。

---

必須ワークフロー

重要：検証せずにエンドポイントを推奨しないでください！

エンドポイントまたは API 操作について尋ねられた場合は、必ず以下の 4 ステップのワークフローに従ってください。

パフォーマンス要件：クエリを並列実行する

ステップ 1～3 は独立したクエリです。複数の Bash ツール呼び出しを使用して、1 つのメッセージ内で並列に実行してください。

ステップ 1：検索して検証する

一致するエンドポイントを検索します（結果は必ず 15～20 件に制限してください）。

jq -r '.paths | keys | map(select(test("KEYWORD"; "i"))) | .[0:15] | .[]' "$SCHEMA"

一般的なパターン：「すべての X を検索」→ /api/v2/X$、「特定の X を取得」→ /api/v2/X/\{id\}

詳しい検索パターンについては、references/search-operations.md を参照してください。

ステップ 2：正確なエンドポイントの存在を確認する

jq '.paths["/api/v2/exact/path"] | keys' "$SCHEMA"

これが null を返す場合、そのエンドポイントは存在しません。先に進まないでください。

ステップ 3：操作の詳細をすべて抽出する

jq '.paths["/api/v2/exact/path"]["METHOD"] | {
  operationId,
  summary,
  description,
  permissions: ."x-inin-requires-permissions",
  parameters: [.parameters[]? | {name, in, required, type, description}]
}' "$SCHEMA"

METHOD を get、post、put、patch、または delete に置き換えてください。

抽出パターンの全容については references/jq-query-patterns.md を、$ref 参照の解決については references/schema-resolution.md を参照してください。

ステップ 4：回答を整形してユーザーに返す

スキーマから実際の結果を使用してステップ 1～3 を完了した後、以下の形式で回答してください。

## Recommended Endpoint

**Endpoint:** `[METHOD] /api/v2/path`
**Operation ID:** `operationId`
**Summary:** Brief description

### Permissions
- Type: ALL/ANY (or "No special permissions required" if null)
- Required: permission list

### Key Parameters
- List path/query/body parameters with required status

### Usage Notes
- Brief guidance on how to use this endpoint
- Any important caveats or considerations

---

禁止事項

• REST パターンからエンドポイントの存在を推測する
• 検証せずにエンドポイントのパスを推測する
• 検証クエリを実行する前にエンドポイントを推奨する
• 一般的な API の慣例に基づく情報を提供する
• 並列実行できるクエリを順番に実行する
• 検索結果を無制限に返す（必ず 15～20 件に制限する）

必須事項

• 推奨する前に、必ず検証クエリを実行する
• 1 つのメッセージ内で複数の Bash ツール呼び出しを使用し、独立したクエリを並列実行する
• 回答にはスキーマの実データを使用する
• .[0:15] などを使用して検索結果を制限する
• 検証に失敗した場合は、不確実であることを明示する（「エンドポイントはスキーマに存在しません」）
• 検索したエンドポイントが見つからない場合は、代替案を提示する
• 構造化されたテンプレートを使用して回答を整形する

---

ワークフローの完全な例

ユーザーからの質問：「すべてのユーザーを検索するには、どの API エンドポイントを使用できますか？」

ステップ 1～3 を並列に実行（3 つの Bash ツール呼び出しを 1 つのメッセージで実行）：

# Tool Call 1: Search for user endpoints
jq -r '.paths | keys | map(select(test("user"; "i"))) | .[0:15] | .[]' "$SCHEMA"

# Tool Call 2: Verify /api/v2/users exists
jq '.paths["/api/v2/users"] | keys' "$SCHEMA"

# Tool Call 3: Get full details for GET /api/v2/users
jq '.paths["/api/v2/users"]["get"] | {
  operationId,
  summary,
  description,
  permissions: ."x-inin-requires-permissions",
  parameters: [.parameters[]? | {name, in, required, type, description}]
}' "$SCHEMA"

ステップ 4：構造化された形式で回答する

## Recommended Endpoint

**Endpoint:** `GET /api/v2/users`
**Operation ID:** `getUsers`
**Summary:** Get the list of available users.

### Permissions
- Type: No special permissions required (permissions is null)

### Key Parameters
- `pageSize` (query, optional): Page size
- `pageNumber` (query, optional): Page number
- `id` (query, optional): A list of user IDs to fetch by bulk
- `sortOrder` (query, optional): Ascending or descending sort order
- `state` (query, optional): Only list users of this state

### Usage Notes
- This endpoint supports pagination via pageSize and pageNumber
- You can fetch specific users by providing an array of IDs in the id parameter
- Use expand parameter to include additional user information

---

リソース

リファレンスドキュメント：

• references/jq-query-patterns.md - jq 構文、高度なフィルタリング、変数の連結に関する包括的な解説
• references/search-operations.md - すべての検索手法、取得前の件数確認パターン
• references/schema-resolution.md - 定義の解決、ネストされた参照、プロパティの抽出
• references/complete-examples.md - 一般的なタスクのステップごとのワークフロー例

外部リソース：

• Swagger 2.0 仕様：https://swagger.io/specification/v2/
• jq マニュアル：https://jqlang.github.io/jq/manual/