メインコンテンツへ移動

共通引数と戻りオブジェクト

このページでは、LCC.assist 系列の API で共通して使用する options、タスクオブジェクト、結果オブジェクト、エラー状態について説明します。

options のフィールド​

フィールド型既定値説明
typestring"text"リクエストタイプです。"text"/"text-reply"、"point"/"pick-point"、"control"/"device-control" のいずれも認識されます。便利なラッパー関数では自動設定されます。
titlestring"脚本请求人工辅助"集中管理側に表示するカードのタイトルです。この既定値は SDK で固定された簡体字中国語の文字列です。
text / promptstring""担当者向けの説明です。具体的な操作を記述し、「補足情報」のような表現は避けてください。
timeoutnumber300待機時間（秒）です。タスク作成時には、バックエンドでの有効期限にも使用されます。
pollIntervalMsnumber1000ポーリング間隔（ミリ秒）です。250 未満は 250 として処理されます。
screenshotLocalPathstringデバイス上のローカルなスクリーンショットファイルです。SDK が集中管理サーバーの files/_temp/assist/lua-script/<udid>/<request-id>/... へアップロードします。
screenshotPathstring集中管理サーバーの files ルートディレクトリにすでにある画像の相対パスです。
screenshotImage / imageImageObjectXXTouch の画像オブジェクトです。SDK が data URL としてエクスポートし、input.imageSrc に設定します。
screenshotImageData / imageDatastringPNG/JPEG 画像のバイナリデータです。SDK が data URL に変換して input.imageSrc に設定します。
screenshotImageFormat / imageFormatstring"jpeg"screenshotImage のエクスポート形式です。"jpeg" または "png" を選択できます。
screenshotImageQuality / imageQualitynumber0.7screenshotImage を JPEG としてエクスポートするときの品質です。範囲は 0.0～1.0 です。
screenshotImageMimeType / imageMimeTypestring自動認識screenshotImageData の MIME タイプです。通常、PNG/JPEG データでは指定する必要はありません。
imageRecttable切り抜き画像をデバイス座標へ対応付けるときに使用します。例：{ left = 100, top = 200, width = 300, height = 120 }。
inputtable{}集中管理側へそのまま渡す追加の構造化情報です。SDK は requestType と scriptRequestId を追加します。

screenshotLocalPath は screenshotPath より優先されます。screenshotLocalPath を渡した場合、SDK はファイルをアップロードし、アップロード後のパスを使用します。

input.imageSrc も screenshotLocalPath / screenshotPath も渡されていない場合、SDK は screenshotImage または screenshotImageData を input.imageSrc へ変換しようとします。ImageObject は呼び出し側が管理し、SDK は自動的に destroy() しません。

ImageObject を直接渡す​

local img = screen.image()
local result, err = LCC.assist.request_control({
    title = "有人対応が必要",
    text = "リモート操作で現在の確認を完了してから「完了」をクリックしてください",
    screenshotImage = img,
    screenshotImageQuality = 0.6,
})
if img.destroy then
    img:destroy()
end

画像データを直接渡す​

local img = screen.image()
local data = img:png_data()
if img.destroy then
    img:destroy()
end

local result, err = LCC.assist.request_control({
    title = "有人対応が必要",
    text = "リモート操作で現在の確認を完了してから「完了」をクリックしてください",
    screenshotImageData = data,
})

画像アドレスを直接渡す​

local result, err = LCC.assist.request_control({
    title = "有人対応が必要",
    text = "リモート操作で現在の確認を完了してから「完了」をクリックしてください",
    input = {
        imageSrc = "data:image/jpeg;base64,...",
    },
})

input.imageSrc はファイルをアップロードせず、screenshotPath にも書き込みません。

メモリを長時間占有しないように、タスクが送信済み、キャンセル、期限切れのいずれかになると、集中管理サーバーはタスクの input から imageSrc を削除します。リクエストの処理中は画像が通常どおり表示されます。

タスクオブジェクト​

task は集中管理側に保存される支援タスクです。主なフィールドは次のとおりです。

{
    id = "assist_xxx",
    kind = "text-reply",
    title = "確認コードを入力",
    prompt = "スクリーンショットを確認して確認コードを入力してください",
    status = "pending",
    deviceId = "デバイス UDID",
    source = "lua-script",
    screenshotPath = "assist/...",
    input = {},
    result = nil,
    createdAt = 1781196058792,
    updatedAt = 1781196058792,
    expiresAt = 1781196358792,
}

時刻フィールドはミリ秒単位のタイムスタンプです。スクリプトが作成したリクエストには、deviceId = device.udid() と source = "lua-script" が自動的に書き込まれます。

結果オブジェクト​

テキスト入力が成功した場合：

{ kind = "text-reply", text = "1234" }

座標選択が成功した場合：

{
    kind = "pick-point",
    x = 123,
    y = 456,
    imageX = 123,
    imageY = 456,
    color = "AABBCC",
}

x と y はデバイスの物理座標で、touch.tap にそのまま使用できます。imageX と imageY はスクリーンショット内の座標です。

有人リモート操作で「完了」をクリックした場合：

{ kind = "device-control", completed = true }

有人リモート操作で「結果を手動送信」を展開し、有効な JSON を送信した場合、result はその JSON に対応する Lua の値になります。たとえば、次の内容を送信します。

{"allowed":true,"reason":"有人確認"}

スクリプトは次の値を受け取ります。

{ allowed = true, reason = "有人確認" }

有人リモート操作で JSON 以外の通常テキストを手動送信した場合：

{ note = "通常のテキスト内容" }

空の内容を手動送信してもタスクは送信されず、スクリプトは待機を続けます。

エラーと状態​

待機に失敗した場合は、次の値を返します。

nil, err, task

主な err：

  • "cancelled"：ユーザーまたはスクリプトがキャンセルしました。
  • "expired"：バックエンドのタスクが期限切れになりました。
  • "timeout"：スクリプトの待機がタイムアウトし、SDK がタスクの取り消しを試みました。
  • "not found"：タスクが存在しません。バックエンドが再起動したか、タスクが削除された可能性があります。
  • その他の文字列：ネットワーク、スクリーンショットのアップロード、バックエンドインターフェースから返されたエラーテキストです。

result が返されるのは submitted 状態だけです。cancelled、expired、timeout のいずれも、有人対応の結果を取得できなかったものとして扱ってください。