ゲーム内HTTPリクエスト

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

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

HTTPリクエストを有効にする

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

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

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

Open Cloudとの使用

HttpServiceは現在、Open Cloudエンドポイントのサブセットを呼び出すことができます。これらのエンドポイントは、HttpServiceを介して他のエンドポイントを呼び出すのと同じ方法で呼び出すことができます。唯一の違いは、リクエストにOpen Cloud 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パスパラメータに..文字列は許可されていません。つまり、たとえば、データストアやエントリにこの文字列が含まれている場合、現在HttpServiceからはアクセスできません。

アセット

バンとブロック

設定

Creator Store

開発者製品

ゲームパス

データとメモリストア

データストア:

メモリストア:

順序付きデータストア:

グループ

インベントリ

ListInventoryItems

Luau実行

通知

CreateUserNotification

プレイス

ユニバース

ユーザー

制限事項

x-api-keyおよびcontent-typeヘッダーのみが許可されています。
x-api-keyヘッダーはSecretである必要があります。詳細はシークレットストアを参照してください。
URLパスパラメータに".."文字列は許可されていません。
HTTPSプロトコルのみがサポートされています。
ポート1194または1024未満のポートは使用できません。ただし、80および443は例外です。ブロックされたポートを使用しようとすると、403 ForbiddenまたはERR_ACCESS_DENIEDエラーが返されます。

レート制限

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

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サーバーの1つを装うことができないように、事前共有された秘密鍵などの安全な認証形式を提供する必要があります。
リクエストが送信されるWebサーバーの一般的な容量とレート制限ポリシーに注意してください。

日本語