AI TOOLS RADAR
製品を申請
すべての Skills / KZKSKI
kzkski/moc-skill

moc-skill

- FIWARE Orion Context Broker (NGSIv2) からエンティティ情報を読み取り専用で取得する。 データ連携基盤・都市OS・スマートシティ基盤・センサーデータ・IoTプラットフォームへの GET クエリ、エンティティ一覧・件数確認、NGSIv2 API 調査が必要なときに能動的に使う。 Orion / NGSIv2 / Context Broker / エンティティ取得 / q クエリ / 地理空間クエリ / Fiware-Service ヘッダー付き基盤アクセスの依頼で発火する。

ソースを見る
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

FIWARE Orion 読み取り専用クエリ

FIWARE Orion Context Broker (NGSIv2) に対して、認証不要の GET のみでエンティティ情報を取得するスキルです。書き込み・Subscription・Registration は実装していません。

インストール

skills CLI でインストールします（OpenCode / Claude Code / Cursor 等に対応）。

bash
npx skills add kzkski/moc-skill -a opencode -y
.agents/skills/moc-skill/scripts/setup-opencode.sh

setup-opencode.sh は OpenCode のツール実行詳細（bash 出力など）をデフォルトで非表示にします。一般ユーザー向けの静かな UI 用です。詳細を見たいときは OpenCode で /details を実行してください。

ローカルパスから試す場合:

bash
npx skills add ./path/to/moc-skill --list
npx skills add ./path/to/moc-skill -a opencode -y
.agents/skills/moc-skill/scripts/setup-opencode.sh

重要: アクセス経路

必ず `scripts/orion.sh` 経由でアクセスすること。 カタログ外 URL へ直接 curl しないでください。対象基盤は endpoints.json に登録された名前だけを使います。

npx skills add 後、moc-skill スキル配下の scripts/orion.sh を絶対パスで実行します。代表パス:

  • .agents/skills/moc-skill/scripts/orion.sh（OpenCode / Cursor 等）
  • .claude/skills/moc-skill/scripts/orion.sh（Claude Code）
  • ~/.config/opencode/skills/moc-skill/scripts/orion.sh（OpenCode グローバル）

エージェントは **/moc-skill/scripts/orion.sh を探索し、見つかったパスを ORION として使ってください。orion.sh は同ディレクトリ隣の endpoints.json を自動解決します。

bash
ORION="/path/to/moc-skill/scripts/orion.sh"

環境変数 ORION_ENDPOINTS_FILE でカタログパスを上書きできます（未設定時はスキル同梱の endpoints.json）。

回答フォーマット

最終回答は一般ユーザーが読みやすい要約にすること。orion.sh の取得結果をそのまま貼り付けない。

  • 一覧・比較・属性値は表または箇条書きで要約する
  • 件数・基盤名・型名・主要属性など、依頼に答える情報だけを含める
  • 実行したコマンド、curl、生 JSON、HTTP ヘッダーなどの技術的な詳細は最終回答に含めない
  • ユーザーが「生 JSON を見せて」「コマンドも教えて」「デバッグ用に全文」などと明示したときだけ技術的な出力を含める

推奨ワークフロー

endpoints.json に登録された makeour.city 系 Orion では `types` を呼ばない（GET /v2/types は 401 Unauthorized）。無駄なリトライを避け、次の順で探索します。

  1. endpoints — 基盤名・Fiware-Service 一覧（各 note）を確認
  2. entities / count — service=（複数サービス時）と type= で直接取得・件数確認
  3. entity — 特定 ID の詳細取得

型名の手がかりは endpoints のサービス note、ユーザーの依頼文、または entities の試行結果から得ます。

bash
"${ORION}" endpoints
"${ORION}" entities sagacity service=moc_sagacity limit=10
"${ORION}" count sagacity service=sagacity_topita type=TopitaPointUser
"${ORION}" entities yokosuka type=WeatherForecast limit=5
"${ORION}" entity yokosuka "forecast-001" attrs=location

コマンドリファレンス

コマンド説明
endpointsカタログに登録された基盤名・URL・Fiware-Service 一覧・説明を表示
types <ep> [service=NAME]GET /v2/types?options=count（makeour.city では 401 のため使用しない）
entities <ep> [k=v ...]GET /v2/entities（未指定時 options=keyValues limit=20 を付与）
entity <ep> <id> [k=v ...]GET /v2/entities/{id}（同上デフォルト付与）
count <ep> [k=v ...]limit=1&options=count で Fiware-Total-Count ヘッダーのみ返す
raw <ep> <path?query> [service=NAME]/v2/ 配下に限定した任意 GET

<ep> は endpoints.json のキー名（例: Sandbox, sagacity, yokosuka）。

複数 Fiware-Service: 1 エントリに配列で複数サービスを登録できます。クエリ時は service=NAME を指定してください（Orion へのクエリパラメータではなく、ヘッダー選択用の予約キー）。単一サービスのエントリでは service= は不要です。

デバッグ

ORION_DRY_RUN=1 を設定すると curl コマンドを表示するだけで実行しません。

bash
ORION_DRY_RUN=1 "${ORION}" entities yokosuka type=WeatherForecast

NGSIv2 クエリパラメータ早見表

entities / entity / count / raw の [k=v ...] または raw のクエリ文字列に指定します。

パラメータ用途
typeEntity Type でフィルタ（例: type=Device）
q属性条件（例: q=temperature>25）
attrs返却属性の限定（例: attrs=location,temperature）
idPatternエンティティ ID の正規表現（例: idPattern=^sensor-.*）
limit最大取得件数（entities/entity デフォルト 20）
offsetページング開始位置
orderByソート（例: orderBy=!dateObserved）
georel + geometry + coords地理空間クエリ（例: georel=near;maxDistance:1000 geometry=Point coords=-3.7,40.4）
optionsレスポンス形式（keyValues, count, values など）

注意点

  • types は使わない: 登録基盤では /v2/types が 401。型探索は entities + type= / count で行う
  • 読み取り専用: POST / PATCH / DELETE / Subscription / Registration は行わない
  • カタログ必須: 未定義のエンドポイント名は拒否される
  • raw は /v2/ のみ: /v2/ 以外へのパスはエラー
  • Entity ID: [A-Za-z0-9._:~-]+ のみ許可（パストラバーサル対策）
  • Fiware ヘッダー: endpoints.json の Fiware-Service / Fiware-ServicePath が空でなければ自動付与。Fiware-Service が配列の場合は service= で選択
  • 依存: curl, jq が PATH に必要

カタログ形式 (endpoints.json)

json
{
  "endpoints": {
    "<名前>": {
      "base_url": "https://orion.<自治体>.makeour.city",
      "Fiware-Service": "単一ヘッダー値",
      "Fiware-ServicePath": "ヘッダー値(不要なら空文字)",
      "note": "説明"
    },
    "sagacity": {
      "base_url": "https://orion.sagacity.makeour.city",
      "Fiware-Service": [
        { "value": "moc_sagacity", "note": "MoC 佐賀" },
        { "value": "sagacity_topita", "note": "Topita" },
        { "value": "sagacity_ikunowa", "note": "保育園データ" }
      ],
      "Fiware-ServicePath": "",
      "note": "複数サービスを1エントリで管理"
    }
  }
}

Fiware-Service は 文字列（単一）または 配列（複数）を指定できます。配列要素は文字列、または value / Fiware-ServicePath / note を持つオブジェクトにできます。エントリ共通の Fiware-ServicePath は、オブジェクト側で未指定の場合のデフォルトになります。

新しい基盤を追加するときは、運用者が提供する Orion URL と Fiware ヘッダー値をこの形式で追記してください。