AgentBay Tap および Swipe API によるクラウドフォン UI 自動化 - AgentBay

このトピックでは、Wuying AgentBay SDK for クラウドフォンの UI 自動化機能について説明します。これらの機能には、タッチ操作、テキスト入力、UI 要素検出、および画面操作が含まれます。

概要

Wuying AgentBay SDK for クラウドフォンの UI 自動化機能には、次のものが含まれます。

タッチ操作: クリックおよびスワイプジェスチャーを使用して、クラウドフォンとインタラクトします。
テキスト入力: テキストを入力し、ハードウェアキーイベントを送信します。
UI 要素検出: UI 要素を検索してインタラクトします。
画面操作: 視覚的検証のためにスクリーンショットをキャプチャします。

セッションの作成

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session
# セッションが正常に作成され、クラウドフォン自動化に使用できます。

タッチ操作

クリックジェスチャー

特定の座標で画面をタップします。

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# 座標をタップします。
result = session.mobile.tap(x=500, y=300)
if result.success:
    print("Tap successful")  # Output: Tap successful
else:
    print(f"Tap failed: {result.error_message}")

agent_bay.delete(session)

スワイプジェスチャー

ある地点から別の地点へスワイプジェスチャーを実行します。

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# 上にスワイプします (下から上へ)。
result = session.mobile.swipe(
    start_x=100,
    start_y=500,
    end_x=100,
    end_y=200,
    duration_ms=300
)
if result.success:
    print("Swipe up successful")  # Output: Swipe up successful

# 左にスワイプします (右から左へ)。
result = session.mobile.swipe(
    start_x=500,
    start_y=300,
    end_x=100,
    end_y=300,
    duration_ms=300
)
if result.success:
    print("Swipe left successful")  # Output: Swipe left successful

agent_bay.delete(session)

パラメーター:

start_x, start_y: 開始座標。
end_x, end_y: 終了座標。
duration_ms: スワイプの持続時間 (ミリ秒)。デフォルト値は 300 です。

テキスト入力

テキストの入力

現在アクティブな入力ボックスにテキストを入力します。

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.input_text("Hello AgentBay!")
if result.success:
    print("Text input successful")  # Output: Text input successful

agent_bay.delete(session)

ハードウェアキーイベントの送信

KeyCode 定数を使用して Android ハードウェアキーイベントを送信します。

from agentbay.mobile.mobile import KeyCode

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# HOME キーを押します。
result = session.mobile.send_key(KeyCode.HOME)
if result.success:
    print("HOME key pressed")  # Output: HOME key pressed

# KeyCode values: HOME=3, BACK=4, VOLUME_UP=24, VOLUME_DOWN=25, POWER=26, MENU=82
print(f"HOME keycode value: {KeyCode.HOME}")  # Output: HOME keycode value: 3

agent_bay.delete(session)

利用可能な KeyCode 定数:

KeyCode	値	説明
`KeyCode.HOME`	3	ホームボタン
`KeyCode.BACK`	4	戻るボタン
`KeyCode.VOLUME_UP`	24	音量アップボタン
`KeyCode.VOLUME_DOWN`	25	音量ダウンボタン
`KeyCode.POWER`	26	電源ボタン
`KeyCode.MENU`	82	メニューボタン

注記: すべてのハードウェアキーはクラウドフォン自動化に使用できます。キーイベントは Android システムに送信され、それに応じて実行されます。

UI 要素の検出

すべての UI 要素の取得

現在の画面階層内のすべての UI 要素を取得します。

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.get_all_ui_elements(timeout_ms=2000)
if result.success:
    print(f"Found {len(result.elements)} UI elements")  # 出力： Found 2172 UI elements
    for element in result.elements:
        # 要素の構造は異なります。要素データを確認してください。
        print(f"Element: {element}")
        # 出力例： 要素データには UI 階層情報が含まれています
else:
    print(f"Failed: {result.error_message}")

agent_bay.delete(session)

パラメータ：

timeout_ms: UI 要素を待機するタイムアウト期間をミリ秒単位で指定します。デフォルト値は 2000 です。

画面操作

スクリーンショットのキャプチャ

現在のクラウドフォン画面のスクリーンショットをキャプチャします：

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"スクリーンショットの URL： {screenshot_url}")
    # 出力： Screenshot URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
else:
    print(f"スクリーンショットのキャプチャに失敗しました： {result.error_message}")

agent_bay.delete(session)

ベストプラクティス

常にクラウドフォン OS イメージを使用する

クラウドフォン UI 自動化には、クラウドフォン OS イメージが必要です。以下の例では、mobile_latest を使用しています：

# 正しい例：クラウドフォン OS イメージを使用します。
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# 間違った例：クラウドフォン操作には使用できません。
session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

スクリーンショット URL の適切な取り扱い

スクリーンショットは画像データではなく、OSS の URL を返します：

result = session.mobile.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"Screenshot available at: {screenshot_url}")
    # 出力例：Screenshot available at: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
    # 必要に応じて、この URL を使用してスクリーンショットをダウンロードまたは表示します。
else:
    print(f"Screenshot failed: {result.error_message}")

適用範囲／利用シーン

例 1：アプリケーション内のナビゲーション

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # アプリケーションアイコンをタップします。
    tap_result = session.mobile.tap(x=200, y=400)
    print(f"アプリケーションタップ結果: {tap_result.success}")  # 出力: アプリケーションタップ結果: True
    
    # アプリケーションのロード完了を待ちます。
    import time
    time.sleep(2)
    
    # スワイプ操作でナビゲーションを行います。
    swipe_result = session.mobile.swipe(
        start_x=400,
        start_y=600,
        end_x=100,
        end_y=600,
        duration_ms=300
    )
    print(f"ナビゲーションスワイプ結果: {swipe_result.success}")  # 出力: ナビゲーションスワイプ結果: True
    
    # ボタンをタップします。
    button_result = session.mobile.tap(x=300, y=800)
    print(f"ボタンタップ結果: {button_result.success}")  # 出力: ボタンタップ結果: True
    
finally:
    agent_bay.delete(session)

例 2：モバイルフォームへの入力

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # ユーザー名フィールドをタップします。
    username_tap = session.mobile.tap(x=300, y=400)
    print(f"ユーザー名フィールドにフォーカス済み: {username_tap.success}")  # 出力: ユーザー名フィールドにフォーカス済み: True
    
    # ユーザー名を入力します。
    username_input = session.mobile.input_text("john_doe")
    print(f"ユーザー名の入力完了: {username_input.success}")  # 出力: ユーザー名の入力完了: True
    
    # パスワードフィールドをタップします。
    password_tap = session.mobile.tap(x=300, y=500)
    print(f"パスワードフィールドにフォーカス済み: {password_tap.success}")  # 出力: パスワードフィールドにフォーカス済み: True
    
    # パスワードを入力します。
    password_input = session.mobile.input_text("secure_password")
    print(f"パスワードの入力完了: {password_input.success}")  # 出力: パスワードの入力完了: True
    
    # ログインボタンをタップします。
    login_tap = session.mobile.tap(x=300, y=650)
    print(f"ログインボタンが押下されました: {login_tap.success}")  # 出力: ログインボタンが押下されました: True
    
finally:
    agent_bay.delete(session)

例 3：UI 要素の検出とインタラクション

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # クリック可能な UI 要素をすべて取得します。
    result = session.mobile.get_clickable_ui_elements(timeout_ms=3000)
    
    if result.success:
        print(f"クリック可能な要素を {len(result.elements)} 個検出しました")  # 出力: クリック可能な要素を 3 個検出しました
        
        # 対象要素を特定するため、要素を解析します。
        for i, element in enumerate(result.elements):
            print(f"要素 {i+1}: {element}")  
            # 例の出力:
            # 要素 1: インタラクション機能を備えた UI 要素
            # 要素 2: インタラクション機能を備えた UI 要素  
            # 要素 3: インタラクション機能を備えた UI 要素
    
    # 検証用にスクリーンショットを取得します。
    screenshot = session.mobile.screenshot()
    if screenshot.success:
        screenshot_url = screenshot.data
        print(f"スクリーンショット URL: {screenshot_url}")
        # 出力: スクリーンショット URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
    
finally:
    agent_bay.delete(session)

例 4：コンテンツのスクロール

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # 複数回、下方向へスクロールします。
    for i in range(3):
        scroll_result = session.mobile.swipe(
            start_x=300,
            start_y=800,
            end_x=300,
            end_y=200,
            duration_ms=400
        )
        print(f"{i+1} 回目の下方向スクロール: {scroll_result.success}")  # 出力: 1 回目の下方向スクロール: True など。
        
        # スクロール間で一時停止します。
        import time
        time.sleep(1)
    
    # 上方向へスクロールします。
    up_result = session.mobile.swipe(
        start_x=300,
        start_y=200,
        end_x=300,
        end_y=800,
        duration_ms=400
    )
    print(f"上方向スクロール結果: {up_result.success}")  # 出力: 上方向スクロール結果: True
    
finally:
    agent_bay.delete(session)

トラブルシューティング

よくある質問

「ツールが見つかりません」というエラー
- クラウドフォンの OS イメージ (例: image_id="mobile_latest") を使用していることを確認してください。
- セッションが正常に作成されたことを確認してください。
- API キーとエンドポイントが正しく設定されているかを確認してください。
ハードウェアキーの操作
- ハードウェアキーの操作は、Android システムにキーイベントを送信します。
- キーが正常に送信されたかを確認するには、result.success のステータスを確認してください。
- エラーハンドリングの例：
```
result = session.mobile.send_key(KeyCode.HOME)
if not result.success:
    print(f"Key press failed: {result.error_message}")
```
UI 要素の検出結果が空になる
- パラメーター timeout_ms の値を増やしてください。
- スクリーンショットをキャプチャして、現在の UI 状態を確認してください。
- ターゲット画面が完全にロードされていることを確認してください。
スクリーンショット URL の処理
- スクリーンショットは画像データではなく、OSS の URL を返します。
- result.data には、画像自体ではなく、ダウンロード URL が含まれています。
- 必要に応じて、その URL を使用してスクリーンショットをダウンロードしてください。
スワイプジェスチャーが期待どおりに動作しない
- 座標が画面の境界内にあることを確認してください。
- さまざまなジェスチャーの速度に対応するために、duration_ms を調整してください。
- 開始座標と終了座標が、意味のあるスワイプ方向を構成していることを確認してください。