ゲーム内のHTTPリクエスト

*このコンテンツは、ベータ版のAI（人工知能）を使用して翻訳されており、エラーが含まれている可能性があります。このページを英語で表示するには、こちらをクリックしてください。

HttpServiceを使用して、分析、データストレージ、エラーロギングなどのユースケース向けにサードパーティのWebサービスに汎用のHTTPリクエストを送信できます。 HttpServiceは特定のOpen Cloudエンドポイントもサポートしています。

HTTPリクエストの有効化

HttpService:GetAsync()、HttpService:PostAsync()、およびHttpService:RequestAsync()メソッドはデフォルトでは有効になっていません。リクエストを送信するには、ゲームのエクスペリエンス設定でHTTPリクエストを許可する必要があります。

プラグインでの使用

StudioのプラグインでHttpServiceを使用して、更新をチェックしたり、コンテンツをダウンロードしたり、その他のビジネスロジックを実行できます。プラグインが初めてサービスを使用しようとしたとき、ユーザーは特定のWebアドレスとの通信をプラグインに許可するように求められる場合があります。ユーザーはプラグイン管理ウィンドウを通じて、いつでもこれらの許可を承認、拒否、取り消すことができます。

プラグインは、localhostおよび127.0.0.1ホストを介して同じコンピュータ上で実行されている他のソフトウェアと通信することも可能です。このようなプラグインに対応したプログラムを実行することで、Studioの通常の機能を超えてプラグインの機能を拡張することができます。たとえば、コンピュータのファイルシステムと連携することができます。そのようなソフトウェアはプラグイン自体とは別に配布する必要があり、セキュリティリスクを伴う可能性があるため注意してください。

Open Cloudとの使用

HttpServiceは現在、Open Cloudエンドポイントのサブセットを呼び出すことができます。これらのエンドポイントは、HttpServiceを通じて他のエンドポイントを呼び出すのと同じ方法で呼び出すことができます。唯一の違いは、リクエストにOpen Cloud APIキーを含める必要があることです：

Open Cloud APIキーを作成します。
APIキーをセキュリティストアに保存します。
リクエストを行います。

以下のコードサンプルは、ゲーム内でユーザーのグループメンバーシップを更新する方法を示しています。


local HttpService = game:GetService("HttpService")

local groupId = "your_group_id"
local membershipId = "your_membership_id"
local roleId = "your_role_id"

local function request()
	local response = HttpService:RequestAsync({
		Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- JSONを送信する場合はこれを設定してください！
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Creator Hubで設定します
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("レスポンスは成功しました:", response.StatusCode, response.StatusMessage)
	else
		print("レスポンスはエラーを返しました:", response.StatusCode, response.StatusMessage)
	end
	print("レスポンス本文:\n", response.Body)
	print("レスポンスヘッダー:\n", HttpService:JSONEncode(response.Headers))
end

-- 安全のために関数をpcall()でラップします
local success, errorMessage = pcall(request)
if not success then
	print("HTTPリクエストの送信に失敗しました:", errorMessage)
end

サポートされているOpen Cloudエンドポイント

次のエンドポイントがサポートされています。現在のHttpServiceの制限により、RobloxドメインへのURLパラメータに..文字列は許可されていません。たとえば、データストアやこの文字列を含むエントリには現在アクセスできません。

アセット

バンとブロック

設定

クリエイターストア

開発者製品

ゲームパス

データおよびメモリストア

データストア：

メモリーストア：

順序付けされたデータストア：

グループ

インベントリ

ListInventoryItems

Luau実行

通知

CreateUserNotification

プレイス

ユニバース

ユーザー

制限事項

x-api-key と content-type ヘッダーのみが許可されています。
x-api-key ヘッダーは Secret でなければなりません。詳細はSecrets storesを参照してください。
URLパラメータに..文字列は許可されていません。
HTTPSプロトコルのみがサポートされています。
ポート1194または1024未満の任意のポートは使用できません。80および443を除きます。ブロックされたポートを使用しようとすると、403 ForbiddenまたはERR_ACCESS_DENIEDエラーが発生します。

レート制限

各Robloxゲームサーバーには、1分あたり2500のOpen Cloudリクエストの制限があります。これを超えると、リクエスト送信メソッドが約30秒間停止する可能性があります。pcall()も、Open Cloud requests exceeded limitというメッセージで失敗する可能性があります。

Open Cloudリクエストは、他のすべてのリクエストで課せられる1分あたり500のHTTPリクエストの同じ全体制限を消費しません。
各エンドポイントには、オーナー（ユーザーまたはグループ）のAPIキーごとに独自の制限があり、呼び出し元に関係なく強制されます（HttpService、Webなど）。

Open Cloudのレート制限、認証ベースのレート制限、およびベストプラクティスについての詳細は、レート制限を参照してください。

ベストプラクティス

HttpServiceの使用を最適化し、制限を超えないようにするために、以下のベストプラクティスを適用してください：

エラーを適切に処理する。Webリクエストは多くの理由で失敗する可能性があります。pcall()を使用して、リクエストが失敗した場合の計画を立ててください。さらに、外部APIから受け取ったすべてのデータを厳密に検証およびサニタイズし、可能な限り正しいデータを保証してください。
指数バックオフを使用して制限を下回る。

リクエストが回復可能なエラーを返す場合、すぐに再試行するのではなく、最初に2秒待ち、その後4秒、8秒、など等間隔をあけて再試行します。これにより混雑を制限し、エンドポイントが「クールダウン」する時間を設けることで、成功するリクエストの可能性を高めます。
データを集約して一括送信します。

可能であれば、複数の小さなリクエストを送るのではなく、必要なすべてのデータを収集して1回のHTTPリクエストで送信することをお勧めします。たとえば、サーバーのすべてのプレイヤーに対してHTTPリクエストを送信する場合、APIにバルク/バッチエンドポイントがあるか確認し、ある場合はすべてのプレイヤーの情報を収集して、1回のリクエストで送信してください。

場合によっては、リクエストのボディにデータを含めるためにHttpService:RequestAsync()を使用する必要があります。
HTTP/2エンドポイントを使用します。HTTP/2は、ヘッダー圧縮や単一接続のリクエスト/レスポンスの多重化などの機能を通じて、重要なパフォーマンス向上を提供します。HttpServiceは、利用可能な場合は自動的にHTTP/2を使用します。HTTP/2仕様では、すべてのヘッダー名を小文字で送信する必要があります。

見える化

可観測性ダッシュボードは、HttpServiceの使用状況を監視およびトラブルシューティングするための洞察と分析を提供します。ダッシュボードには、ゲームからのHttpServiceリクエストのボリュームを追跡するリクエスト数と、エンドポイントが応答するまでのレイテンシーを測定する応答時間の2つの主なチャートがあります。

フィルタリングおよび内訳のための利用可能な次元は次のように定義されています：

リクエストタイプ

GET
POST
PUT
PATCH
DELETE
その他（指定されていないリクエストタイプ用）

ステータス

成功（HTTP 1xxおよび2xxステータスコード）
リダイレクト（HTTP 3xxステータスコード）
400（不正なリクエスト）
401（認証されていない）
403（禁止されている）
404（見つかりません）
429（リクエストが多すぎます）
500（内部サーバーエラー）
503（サービス利用不可）
ExternalError（外部サービスから返された他の指定されていないエラーコード）
InternalError（Roblox内のHttpServiceから返された問題）

応答時間チャートはステータスデータと相関関係がありません。「ステータス」を内訳またはフィルターとして選択すると、このチャートはデータを表示しません。

追加の考慮事項

リクエストは、悪意のある行為者があなたのRobloxサーバーの一つとして振る舞えないように、事前共有の秘密鍵など、安全な形の認証を提供する必要があります。
リクエストが送信されるWebサーバーの一般的なキャパシティやレート制限ポリシーに注意してください。

日本語