顧客ブランドの観測を始める
この依頼で使う
「顧客のブランド計測を、自社の作業と分けて始めたい」
取得前に決める
顧客、ワークスペースの所有者、ブランド、質問、測定枠を確認します。別顧客の対象を使わず、最初の観測まで読み戻して確認します。
一つのアカウントから顧客用または提案用ワークスペースを作り、ブランド・質問と最初の観測結果を確認します。
前提条件
顧客ワークスペースを管理できる権限を持つアカウントで認証します。組織スコープの書き込みキーと、workspace access を持つ人間の agency operator を用意します。書き込みや観測実行の前に対象顧客を確認します。
作成主体とアクセス境界
組織キーは、組織のワークスペース一覧・利用枠・作成と、同じ組織の既存メンバーを一つの workspace に割り当てる control-plane 操作に使います。組織キー自身は Workspace data credential ではありません。orc whoami を組織キーで実行したときの principalType: api_key と apikey:... の ID を、人間の --user-id として使わないでください。
許可された人間の agency operator を別の named profile で認証し、その profile の orc whoami --json に返る data.user.id を YOUR_OPERATOR_USER_ID とします。組織キー profile から次を実行すると、active な組織メンバーに対象 workspace の access を一つだけ付与できます。
ORCHESTOR_PROFILE=agency-org orc workspaces members create YOUR_CLIENT_WORKSPACE_ID --user-id YOUR_OPERATOR_USER_ID --workspace-role owner --idempotency-key YOUR_GRANT_IDEMPOTENCY_KEY --jsonこの操作は対象 workspace が組織キーと同じ組織に属することと、指定 user が active な組織メンバーであることを確認します。付与前の X-Workspace-ID は access grant になりません。ブラウザーを使う場合も、POST /v1/workspaces/current/selection は人間の active membership を検証して設定を保存するだけで、membership を作成しません。CLI では付与後に operator profile で orc workspace use または各データコマンドの --workspace を使います。
組織キーを使う操作と Workspace data の操作を profile で分けます。workspaces quotas get は組織の利用枠なので組織キーで実行し、workspace-scoped key では実行しません。自動化用の read key が必要なら、付与後に人間の operator profile から orc api-keys create --scope workspace --workspace YOUR_CLIENT_WORKSPACE_ID --type read_only --output NEW_PRIVATE_KEY_FILE を実行します。組織キーや組織スコープの service-account key を Workspace data の読み取りに転用する経路はありません。
クイックリファレンス
プレースホルダーは前の操作で返された ID に置き換えます。確認しながら進める一覧であり、一括実行するスクリプトではありません。
ORCHESTOR_PROFILE=agency-org orc auth status --json
ORCHESTOR_PROFILE=agency-operator orc whoami --json
ORCHESTOR_PROFILE=agency-org orc workspaces list --json
ORCHESTOR_PROFILE=agency-org orc workspaces quotas get --json
ORCHESTOR_PROFILE=agency-org orc workspaces create --name "YOUR_CLIENT_WORKSPACE_NAME" --purpose client --brand '{"name":"YOUR_BRAND_NAME","domain":"YOUR_BRAND_DOMAIN"}' --default-country-code JP --default-language-code ja --idempotency-key YOUR_IDEMPOTENCY_KEY --json
ORCHESTOR_PROFILE=agency-org orc workspaces members create YOUR_CLIENT_WORKSPACE_ID --user-id YOUR_OPERATOR_USER_ID --workspace-role owner --idempotency-key YOUR_GRANT_IDEMPOTENCY_KEY --json
ORCHESTOR_PROFILE=agency-operator orc workspace use YOUR_CLIENT_WORKSPACE_ID
ORCHESTOR_PROFILE=agency-operator orc workspace current --json
ORCHESTOR_PROFILE=agency-operator orc workspaces setup get --workspace YOUR_CLIENT_WORKSPACE_ID --json
ORCHESTOR_PROFILE=agency-operator orc brands list --workspace YOUR_CLIENT_WORKSPACE_ID --json
ORCHESTOR_PROFILE=agency-operator orc prompts list --workspace YOUR_CLIENT_WORKSPACE_ID --json
ORCHESTOR_PROFILE=agency-operator orc reports visibility get --workspace YOUR_CLIENT_WORKSPACE_ID --json1. 接続先と既存の顧客を確認する
同じ顧客のワークスペースが存在すれば、その ID を使います。顧客 A と顧客 B の ID を混ぜないよう、各コマンドに対象を明示します。
2. 顧客用または提案用ワークスペースを作成する
継続運用を始める顧客には --purpose client を使います。提案段階では、代理店組織に --purpose pitch で提案用ワークスペースを作成します。目的に合う作成コマンドを一つ選びます。
ORCHESTOR_PROFILE=agency-org orc workspaces create --name "YOUR_PITCH_WORKSPACE_NAME" --purpose pitch --brand '{"name":"YOUR_BRAND_NAME","domain":"YOUR_BRAND_DOMAIN"}' --default-country-code JP --default-language-code ja --idempotency-key YOUR_PITCH_IDEMPOTENCY_KEY --json以降のコマンドには、返された提案用ワークスペース ID を指定します。提案用の作成には、月間作成枠 pitch_workspaces と同時利用枠 active_pitch_workspaces の両方が必要です。作成前に remaining と unlimited を確認します。有効期限は作成から7日間で、作成結果の expires_at で確認できます。別の顧客を追加するときは、名前・ブランド・idempotency key を変えて作成します。
workspaces create に顧客ブランド、国、言語をまとめて渡します。組織キーで作成した workspace には自動で人間 membership は追加されないため、返された ID を使って前節の members create を実行します。付与が成功したら operator profile で orc workspace use YOUR_CLIENT_WORKSPACE_ID を実行します。workspaces setup get は現在のセットアップ状態を返します。処理中は再実行し、初回 batch の状態と blocker を確認してからレポートへ進みます。npm CLI 0.6.0（beta タグ）以降では、--wait を付けて完了まで待つこともできます。
3. アクセス権を付与して workspace を選択する
YOUR_OPERATOR_USER_ID は組織に所属する人間の user ID にします。組織キーの synthetic ID は使いません。付与後に operator profile の orc workspace use または --workspace が成功することを確認してから、Workspace data を読みます。権限不足なら付与を繰り返すのではなく、operator の組織 membership と role を確認します。
4. 生成されたブランドと質問を確認する
brands list と prompts list に同じワークスペース ID を指定します。別顧客のブランドや質問が混ざっていないことを確認します。新しい workspace の場合、セットアップ処理中に一時的に空の一覧が返ることがあります。
5. 最初の観測結果を読む
reports visibility get に同じワークスペース ID を指定します。データがない場合は、workspaces setup get の結果で初回 batch の失敗や blocker を確認します。
検証後に pause した pitch workspace も、同じ members create → operator の workspace use → setup/brands/prompts/report read の順でアクセスを回復できます。read のためだけに組織キーの Workspace header を付けたり、別の組織キーを作ったりしません。観測を再開する場合だけ、access を確認した人間 operator が orc workspaces resume YOUR_PITCH_WORKSPACE_ID --idempotency-key YOUR_RESUME_IDEMPOTENCY_KEY --yes --json を実行します。
途中で止まった場合
workspaces create の応答を受け取れなかった場合は、同じ idempotency key で同じ request を再送します。作成済みの顧客や質問は重複しません。セットアップ待機が止まった場合は、同じワークスペース ID で workspaces setup get を再実行します。
次に進む
受注後は、同じ提案用ワークスペースを継続運用へ移すことで観測履歴を引き継ぎます。この変換には npm CLI 0.6.0（beta タグ）以降を使います。顧客を追加する前に、顧客ごとの利用枠を確認する手順も参照してください。
失敗が残る場合は、失敗を報告して再検証するで、このワークフローと失敗した手順を報告へ添えます。