エクスペリエンス設定 | 文書 - Roblox クリエーターハブ

configs APIは、Creator HubやStudioを使用するのではなく、プログラム的にエクスペリエンス設定を管理できます。このガイドでは、一般的なフローを説明します：

ドラフト設定を作成または更新する。
公開する。
最新の設定値を取得する。
バージョン履歴を使用して以前の値にロールバックする。

公開した値は、すぐにあなたのエクスペリエンスで利用可能になります。サーバースクリプトでは、ConfigServiceを使用して設定を読み込み、リアルタイムの更新に反応します。ConfigService:GetConfigAsync()およびConfigSnapshot:GetValue()を使用して値を読み取り、ConfigSnapshot.UpdateAvailableとConfigSnapshot:Refresh()またはConfigSnapshot:GetValueChangedSignal()によって値が変更されたときに反応できます。Luauコードのサンプルや詳しい情報については、コードに設定を追加するおよびスナップショットを更新するをエクスペリエンス設定ガイドでご覧ください。

始める前に、APIキーを生成するか、OAuth 2.0アプリを設定してください。読み取り操作にはuniverse:readスコープが必要です。書き込み操作（ドラフト、公開、復元）にはuniverse:writeが必要です。

すべてのエンドポイントはあなたのユニバースIDを使用します。ユニバースIDはCreator Dashboardで確認できます。エクスペリエンスタイルのオーバーフローメニューをクリックし、ユニバースIDをコピーします。

完全なエンドポイントのリファレンス、リクエストおよびレスポンススキーマ、エラーコードについては、Cloud APIリファレンスを参照してください。

リポジトリ

configsエンドポイントへのリクエストは、パスにリポジトリを使用し、リクエストボディにentriesオブジェクトを持ちます。たとえば、このリクエストはドラフト設定を追加します：


PATCH /creator-configs-public-api/v1/configs/universes/<UNIVERSE_ID>/repositories/<REPOSITORY>/draft
{
  "entries": {
    "enableNewTutorial": true
  }
}

リポジトリは製品ごとに異なり、設定をシステムで分けます。
entriesは、設定のキーと値のペアです。キーと値のシンプルなオブジェクトを送受信します。

このガイドでは、エクスペリエンス内の設定をカバーしているため、すべてのリクエストでInExperienceConfigをリポジトリとして使用します。リポジトリは最終的に追加の製品やユースケースをカバーするために拡張されます。

ユースケース	リポジトリ
エクスペリエンス内の設定	InExperienceConfig

設定の作成または更新

公開前は、設定の変更はドラフトとしてステージングされます。全体の設定を一度の操作で設定するか、満足するまで部分的な更新を行うことができます：

ゼロから始めるか、すべてを置き換える場合 — オーバーライトエンドポイントを使用し、ペイロードを完全な望ましい状態にします。省略したキーは削除されたと見なされます。
一部のキーのみを変更する場合 — 部分更新エンドポイントを使用し、送信したキーのみを更新します。他のすべてはそのままです。

このサンプルコードはbossHealthを100に設定し、オーバーライトエンドポイントを使用します：


import requests

API_KEY = "<API_KEY>"
UNIVERSE_ID = "<UNIVERSE_ID>"
BASE = f"https://apis.roblox.com/creator-configs-public-api/v1/configs/universes/{UNIVERSE_ID}/repositories/InExperienceConfig"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# オプション：既存のドラフトがあり、楽観的同時実行性を使用したい場合はpreviousDraftHashを送信
payload = {
    "entries": {
        "bossHealth": 100
    }
}
r = requests.put(f"{BASE}/draft:overwrite", headers=headers, json=payload)
r.raise_for_status()
draft = r.json()
draft_hash = draft["draftHash"]  # 公開のためにこれを保持
print("ドラフトがステージングされました。draftHash:", draft_hash)

レスポンスにはdraftHash値が含まれています。このハッシュは公開のために必要です。ドラフト内で一部のキーだけを変更したい場合は、/draftエンドポイントのPATCHメソッドを使用し、変更したいエントリ（キー）のみを送信してください。

ドラフトハッシュについて

ドラフトハッシュは、現在のドラフトの状態を示す不透明な識別子です。APIはドラフトに対するリードまたは書き込み操作（作成、更新、オーバーライト、リセット、復元）の後にこれを返します。

ドラフトを更新または公開するときは、リクエストボディにpreviousDraftHashを送信できます。もしサーバーの現在のドラフトとハッシュが一致しない場合（例：他の誰かがその間に公開または編集した）、リクエストは失敗します。その場合、更新されたドラフトを再読み込みし、新しいハッシュを取得して再試行または変更をマージできます。

公開を呼び出す前や、previousDraftHashを使用する場合に別のドラフト変更を行う前に、必ず最後のドラフトレスポンスからdraftHashを保存してください。

変更を公開する

ドラフトに満足できたら、それを公開して新しい値をライブにします。ドラフトレスポンスからのdraftHash、バージョン履歴の目的のためのmessage、およびdeploymentStrategy（GradualRolloutで15分のロールアウトまたはImmediateのいずれか）を渡します。以下のサンプルコードは、設定を即座に展開します：


publish_payload = {
    "draftHash": draft_hash,
    "message": "ボスの体力を100に設定",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("公開されました。configVersion:", result["configVersion"])

成功した公開の後、ドラフトはクリアされ、あなたのエクスペリエンスは展開戦略に従って新しい設定を受け取ります。レスポンスには新しい設定バージョンが含まれます：


{
  "configVersion": 6
}

公開された設定を取得する

変更が反映されたことを確認するため、最新の公開設定を取得します。キーと値のみが必要な場合は値のみのエンドポイントを使用し、メタデータ（説明、最終アクセス時間など）も必要な場合は完全なエンドポイントを使用します。このサンプルコードは、値のみのエンドポイントを使用し、完全なエンドポイントはコメントアウトされています：


# 値のみ（RCCとあなたのゲームが見る形状）
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("公開されたbossHealth:", boss_health)  # 100であるべき

# または、完全なメタデータで：
# r = requests.get(f"{BASE}/full", headers=headers)

entries.bossHealth（またはあなたのキー）が、あなたが公開した内容と一致していることを確認してください。

履歴を確認し、ロールバックする

すべての公開はリビジョンを作成します。これはバージョン管理システムと同じです。誰が何を変更したか、いつ変更したかを確認するためにリビジョンをリストし、必要に応じて以前のリビジョンに戻すことができます。

このサンプルコードはリビジョンエンドポイントを呼び出し、結果を表示します。各リビジョンにはrevisionId、version、time、publishedBy、message、およびchanges（キー、"before"値、および"after"値）が含まれます。


r = requests.get(f"{BASE}/revisions", headers=headers, params={"MaxPageSize": 10})
r.raise_for_status()
data = r.json()
for rev in data["revisions"]:
    print(rev["version"], rev["time"], rev["message"], "— revisionId:", rev["revisionId"])

ロールバックするには、復元したいrevisionIdを使って復元エンドポイントを呼び出します。これにより現在のドラフトがクリアされ、リバートコミットがステージングされます。これは公開ではありません。公開するには、返されたdraftHashを使用してpublishを呼び出す必要があります。新しい変更を公開するのと同じように。


REVISION_ID = "1234567890"  # 上記のリストから
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# リバートを公開
publish_payload = {
    "draftHash": restore_hash,
    "message": "前の設定にロールバック",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("ロールバックが公開されました。configVersion:", r.json()["configVersion"])

制限事項

制限	最大
リポジトリごとのキー	100
キーの長さ	256文字

これらの制限を超えるリクエストは失敗します。あなたのエクスペリエンスにおける型特有の値の制限（例：文字列対JSON）については、制限をエクスペリエンス設定ガイドで参照してください。

このガイドのすべてのエンドポイントに関する詳細については、Cloud APIリファレンスを参照してください。