初回観測を実行して結果を読む
サインインし、使用するワークスペースを選んでから進めます。別の対象なら新しいワークスペースを作成します。以下のWORKSPACE_IDとサイトURLを実際の対象に置き換えます。JSONの編集にはjqを使います。
ベータユーザーはブラウザーで認証したCLIの資格情報を使えます。APIキーで実行する場合は、対象ワークスペースの観測利用枠とread_write権限が必要です。
1. サイトから設定候補を生成する
orc observations create --workspace WORKSPACE_ID \
--website https://example.com --region JP --language ja \
--wait --timeout 10m --json
orc observations configurations get --workspace WORKSPACE_ID --json > configuration.json設定生成が成功したら、ブランド、競合、トピック、プロンプト、観測地域・言語・モデルを確認します。この時点では候補を生成した状態です。初回観測は次の確定で始まります。
2. 確定する内容を用意する
取得結果には表示用の情報も含まれます。次の変換で確定APIが受け取る項目を取り出し、confirmation.jsonを編集します。以下は候補を維持し、未指定の選択状態を有効にする例です。
jq '.data | {
monitoring_scope_id,
brand: (.brand | {id, name, domain, description, industry, identity, products,
audience: [.audience[] | {label, description, percentage, enabled: true}]}),
competitors: [.competitors[] | {id, name, domain, selected: (if .selected == null then true else .selected end)}],
topics: [.topics[] | {id, name, selected: (if .selected == null then true else .selected end)}],
prompts: [.prompts[] | {id, topic_id, text, selected: (if .selected == null then true else .selected end)}],
dimensions: (.dimensions | {engine, model_channel, region, language})
} + (if has("platform_selection") then {platform_selection} else {} end)' \
configuration.json > confirmation.json観測するプロンプトとモデルを確認してから確定します。確定は観測を開始する書き込み操作です。
orc observations configurations confirm --workspace WORKSPACE_ID \
--stdin --json < confirmation.json > confirmation-result.json
INITIAL_BATCH_ID=$(jq -er '.data.initial_batch_id' confirmation-result.json)initial_batch_idが返ったことを確認します。返らない場合は、確定結果とセットアップ状態を確認し、観測が始まったとは扱いません。
3. 初回観測を待ち、結果を読む
orc runs batches get "$INITIAL_BATCH_ID" --workspace WORKSPACE_ID --wait --timeout 10m --json
orc runs batches get "$INITIAL_BATCH_ID" --workspace WORKSPACE_ID --json
orc runs batches results get "$INITIAL_BATCH_ID" --workspace WORKSPACE_ID --json
orc workspaces setup get --workspace WORKSPACE_ID --json同じバッチの状態がcompletedになり、実際の回答・結果が取得できたことを確認します。空の結果、設定生成の成功、確定の受付だけを「初回観測完了」として扱いません。
WebのWelcomeも同じ設定生成・確定APIを使います。ただし、Welcome画面の終了を示すcompleted_atと、初回観測バッチの完了は別の状態です。CLI 0.5.0にはWelcome終了のコマンドがないため、Webで終了が残っている場合はWelcomeで進めます。
中断・失敗から再開する
| 停止した段階 | 確認と再開 |
|---|---|
| 認証・対象 | orc auth status --jsonと対象IDを確認。登録し直さない。 |
| 設定生成 | orc observations get --workspace WORKSPACE_ID --jsonで状態とエラーを読む。原因を解消後、同じURL・ワークスペースでobservations createを再実行する。 |
| 利用枠 | measurement_quota_exhaustedは担当者に対象IDとエラーを伝える。招待入力や再試行だけで解決したとは扱わない。 |
| 候補の確認 | 保存したconfiguration.jsonを確認し、確定へ進む。ワークスペースを作り直さない。 |
| 観測待機のタイムアウト | サーバーの処理は継続する。同じINITIAL_BATCH_IDで状態確認と待機を再開する。 |
設定生成から初回観測までをまとめて実行する
init --websiteは公開済みネイティブ版v0.6.30で利用できます。CLI 0.5.0には未収録です。orc init --helpに--websiteがある版でのみ、以下を使います。0.5.0では上記の段階別コマンドを使ってください。
orc init --workspace WORKSPACE_ID --website https://example.com \
--region JP --language ja --timeout 10m --json生成候補をまとめて確定し、初回バッチを待ちます。編集してから確定する場合は--no-confirmを付け、生成後に手順2へ進みます。initは新規登録やワークスペース作成を行いません。