GS2-Script のユーティリティメソッド

GS2-Script で実行する Lua スクリプト内で利用可能なユーティリティメソッドの説明

Tags:

Script

GS2-Scriptの拡張スクリプト（Lua言語）で使用可能な拡張メソッドです。

GS2-Script のサンドボックス内で利用できる Lua 標準ライブラリには制限があります。 load / require / dofile / pcall のような外部リソースを読み込んだり、エラーを内部でハンドリングしたりする関数は使用できません。 os ライブラリも安全のため、os.time() のみが利用可能です。 table / string / math ライブラリは概ねそのまま利用できます。

util.table_to_json

Luaのテーブル型（配列）を、JSON形式の文字列に変換します。

Request

引数名	型	説明
table	table	Luaテーブル

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	string	変換結果のJSON文字列

Sample

Code

result = util.table_to_json({a="a", b=1, c=false})
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
json_str = result["result"]

Output

{"a":"a","b":1,"c":false}

util.json_to_table

JSON形式の文字列を、Luaのテーブル型（配列）に変換します。

Request

引数名	型	説明
jsonText	string	JSON形式の文字列
disableNumberStringToNumber	bool	JSON内に文字列型で数値が格納されていた時に数値型に変換しない(default: false)

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	table	変換結果のLuaテーブル

Sample

Code

result = util.json_to_table("{\"a\": \"a\", \"b\": 1, \"c\": false}")
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
json_table = result["result"]

util.split

文字列を分割します。

Request

引数名	型	説明
value	string	元の文字列
sep	string	デリミタ、区切り文字列

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	table	分割した文字列のLuaテーブル

Sample

Code

result = util.split("a,b,c", ",")
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
split_table = result["result"]
print(split_table[1])
print(split_table[2])
print(split_table[3])

Output

a
b
c

http.get

HTTPのGETリクエストを発行します。

Request

引数名	型	説明
url	string	接続先のURL

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	string	HTTPレスポンスのボディ

Sample

Code

result = http.get("https://example.com")
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
get_result = result["result"]

http.post

HTTPのPOSTリクエストを発行します。

Request

引数名	型	説明
url	string	接続先のURL
contentType	string	HTTPヘッダーのContent-Type
body	string	HTTPリクエストメッセージのボディ

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	string	HTTPレスポンスのボディ

Sample

Code

result = http.post("https://example.com", "application/json", "{\"a\": 1}")
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
post_result = result["result"]

util.random

0 〜 1 の浮動小数点数の乱数を生成する

Request

引数名	型	説明

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	float	生成した乱数

Sample

Code

result = util.random()
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
random_value = result["result"]

util.uuid

UUIDv4 に基づく文字列を生成する

Request

引数名	型	説明

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	float	生成したUUID

Sample

Code

result = util.uuid()
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
random_value = result["result"]

util.shared_random

抽選機能などで《同一の乱数列を再現したい》ケースのために、シードと連番に基づく決定論的な乱数を生成します。スタンプシートの自動リトライによる再実行時にも、同じ乱数列が得られるように設計されています。

category ごとに独立した連番が管理されるため、同一スクリプト内で複数の独立した乱数列が必要な場合に使い分けられます。

Request

引数名	型	説明
category	int	乱数列を区別するためのカテゴリ番号

Result

メンバ名	型	説明
isError	bool	エラーの有無
statusCode	int	ステータスコード
errorMessage	string	エラーメッセージ
result	float	生成した乱数

Sample

Code

result = util.shared_random(1)
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end
shared_value = result["result"]

fail

スクリプトの実行を失敗扱いで中断し、呼び出し元の API にエラーを返します。事前スクリプト/事後スクリプトでバリデーションを行い、条件を満たさない場合にエラーを返したい場合に使用します。

Request

引数名	型	説明
errorCode	string	返却するエラーコード（`BadRequest` / `Unauthorized` / `NotFound` / `Conflict` / `ServiceUnavailable` / `BadGateway` 等。HTTP ステータスコード（`400` / `401` 等）も指定可能）
message	string	エラーメッセージ

errorCode に該当しない値を指定した場合は InternalServerError として処理されます。

Sample

if not_allowed then
  fail("BadRequest", "validation.error.notAllowed")
end

print

ログに任意の文字列を出力します。GS2-Log を有効化している場合、出力した内容はアクセスログから確認できます。スクリプト内のデバッグや、実行経路の記録に利用してください。

Request

引数名	型	説明
message	string	出力するメッセージ

Sample

print("invoked with userId=" .. args.userId)

os.time

スクリプトの実行時点のサーバー時刻を Unix 時間（秒）で取得します。 GS2-Distributor の時刻オフセット機能を利用している場合、その分のオフセットが反映された時刻が返ります。

Sample

now = os.time()

gs2

GS2-Script の Lua スクリプト内から、GS2 の各マイクロサービスの API を直接呼び出すためのクライアントです。呼び出すサービス名を引数に取り、続けて API 名と引数を指定します。

呼び出した API がトランザクションを発行する場合、その発行内容はスクリプトを起動した API のトランザクションと合わせて返却されます。

Sample

GS2-Inventory のアイテムを取得する例:

result = gs2("inventory").get_item_set_by_user_id({
  namespaceName = "namespace-0001",
  userId = args.userId,
  inventoryName = "inventory-0001",
  itemName = "item-0001",
})
if result.isError then
  fail(result['statusCode'], result['errorMessage'])
end

利用可能なサービス名・API 名は、各マイクロサービスの API リファレンスを参照してください。