segment-manager

セグメントマネージャー

目的

セグメントのライフサイクル全般を管理します。セグメントの一覧表示、取得、作成、更新、削除、FilterQL の検証、セグメントサイズの推定を行います。

環境

認証済みの API アクセスが必要です。認証情報の解決については ../references/auth.md を参照してください。

API エンドポイント

セグメントの一覧表示

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&kind=segment&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

クエリパラメーター：table、kind、valid、sizes

セグメントの取得

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}?sizes=true&inline=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

クエリパラメーター：sizes（サイズデータを含める）、inline（含まれるセグメントをインライン化する）

セグメントの祖先の取得

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}/ancestors" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

セグメントの作成

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Segment Name",
    "slug_name": "segment_slug",
    "description": "What this segment represents",
    "segment_ql": "FILTER condition FROM user ALIAS segment_slug",
    "kind": "segment",
    "table": "user",
    "is_public": true,
    "tags": [],
    "save_hist": true
  }'

セグメントの更新

curl -s -X PUT "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... updated fields ... }'

セグメントの削除

curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

FilterQL の検証

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (country = "US", visitct > 5) FROM user ALIAS test'

有効な場合は 200 を返し、無効な場合はエラーメッセージを返します。

セグメントサイズの推定（アドホックな FilterQL）

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER condition FROM user'

本文には JSON ではなく、生の FilterQL テキストを指定します。

既存のセグメントサイズの取得

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

セグメントのフィールド情報 — オーディエンススナップショット

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

セグメント内の各フィールドの分析情報として、値の分布、カバー率、数値統計、ヒストグラムを返します。 クエリパラメーター：fields（カンマ区切り）、limit（デフォルトは 20、最大 1000）、table、cached。 詳細な分析には、audience-snapshot skill を使用してください。

セグメントの再評価

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/reevaluate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"id": "segment_id"}'

セグメントのペイロード

作成に必須のフィールド：

{
  "name": "Display Name",
  "slug_name": "url_friendly_slug",
  "description": "Human-readable description",
  "segment_ql": "FILTER ... FROM user ALIAS slug",
  "kind": "segment",
  "table": "user",
  "is_public": true,
  "save_hist": true
}

任意のフィールド：

{
  "tags": ["tag1", "tag2"],
  "groups": ["group_id"],
  "expires_at": "2025-12-31T00:00:00Z",
  "emit_trigger": false,
  "schedule_exit": false
}

セグメントの種類

種類	説明	ユースケース
segment	標準的なオーディエンスセグメント	一般的なオーディエンスターゲティング
aspect	構成要素となるセグメント	再利用可能なフィルターコンポーネント
goal	ビジネス目標	コンバージョンのトラッキング
list	期間指定のエクスポートリスト	1 回限りまたは定期的なエクスポート
conversion	キャンペーンのトラッキング	アトリビューション測定
metric	指標セグメント	分析／レポート作成
managed	システム管理対象	プラットフォーム内部での使用
candidate	意思決定の除外対象	意思決定から除外

動作

読み取り操作（list、get、size）の場合

直ちに実行して結果を表示します。

書き込み操作（create、update、delete）の場合

確認ゲートパターンを使用します。

1. ペイロード全体を作成します
2. 人が読める形式の概要を表示します
3. 生の API ペイロードを表示します
4. ユーザーの確認を待ちます
5. 承認されたら実行します

検証フロー

セグメントを作成または更新する前に、次の手順を行います。

1. POST /api/segment/validate で FilterQL を検証します
2. 無効な場合は、エラーを解析して修正を試みます（最大 3 回再試行）
3. 有効になったら、POST /api/segment/size でサイズを推定します
4. 先に進む前に、検証結果とサイズを提示します

エラー処理

• 無効な FilterQL：検証エラーを解析し、問題を特定して修正を提案します
• スラッグの競合（409）：別のスラッグ名を提案します
• 空のセグメント（サイズ 0）：ユーザーに警告し、条件を広げるよう提案します
• 非常に大きなセグメント：サイズを伝え、意図を確認します

依存関係

• 使用：../references/auth.md、../references/api-client.md、../references/confirmation-gate.md
• 参照：../references/filterql-grammar.md