developer-device-platform-device-run

Developer Device Platform：Device Run

Device Run はリモート DDP デバイスでジョブを実行し、そのアーティファクト（ログ、取得したファイル）を Cloud Storage バケットに返します。1 つのセッションから、指定されたデバイスごとに 1 つのジョブが実行されます。

警告

Developer Device Platform（DDP）は現在プレビュー版です。 gcloud beta device-run コマンドは予告なく変更される場合があります。

このスキルを使用する場面

ユーザーの要望	使用するもの
リモートデバイスでネイティブバイナリまたはシェルスクリプトを実行する	このスキル（android-executable）
リモートデバイスで Android インストルメンテーションテスト APK を実行する	このスキル（instrumentation）
デバイスを予約し、adb で接続して、画面をストリーミングする	developer-device-platform-basics
インタラクティブなデバイスリースを延長またはキャンセルする	developer-device-platform-basics
USB 経由で接続されたデバイスを操作する	どちらでもありません（DDP ではありません）

以下のセットアップは完了しているため、このスキルは認証、プロジェクトの選択、API の有効化に関して別のスキルに依存しません。

このスキルで対応しないリクエスト

インタラクティブな利用（デバイスの予約、adb、画面のストリーミング、リース）の場合：

• developer-device-platform-basics がインストールされている場合： Device Run セッションを送信しないでください。developer-device-platform-basics に切り替え、インタラクティブな予約もアクティブなプロジェクトに課金されることを伝えてください。
• developer-device-platform-basics がインストールされていない場合： ツールを一切呼び出さず（コマンド、検索、ファイルの読み取り、スケジュール設定を含む）、1 つのメッセージで返信してから終了してください：
  1. Device Run は非インタラクティブなバッチジョブ向けであるため、Device Run セッションは送信しないと伝えてください。
  2. developer-device-platform-basics スキルを使用したインタラクティブな Device Streaming 予約を案内してください（または https://docs.cloud.google.com/device-streaming/docs/overview.md.txt を案内してください）。あわせて、スキルのインストールを提案してください。
  3. インタラクティブな予約もアクティブな Google Cloud プロジェクトに課金されることを警告してください。

すばやく回答する

Device Run の構文を広くウェブ検索するより、このスキルと gcloud beta device-run ... --help を優先してください。gcloud または beta コンポーネントがインストールされていない場合は、公式ドキュメント https://docs.cloud.google.com/developer-device-platform/device-run.md.txt および https://docs.cloud.google.com/sdk/gcloud/reference/beta/device-run を参照してください。ドライランの場合は、コマンドを実行せずに表示してください。

Usage Attribution

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 Usage Attribution の指示を必ず読み、それに従ってください。

セットアップ

環境ごとに、これらの確認を一度実行します。ツールがインストール済みだと決めつけず、ユーザーの承認なしにソフトウェアをインストールまたは更新しないでください。

1. gcloud CLI：gcloud がインストールされ、Device Run コマンドが使用できることを確認します。

   gcloud --version
   gcloud beta device-run sessions submit android-executable --help >/dev/null
   

   gcloud がない場合は、ユーザーに https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt を案内してください。beta コンポーネントまたは Device Run コマンドがない場合は、gcloud components install beta または gcloud components update を実行する前に、ユーザーに確認してください。

2. 認証：有効なアカウントを確認します。Compute Engine またはその他の リモート VM では、有効なアカウントが VM のデフォルトのサービスアカウント （[email protected]）の場合があります。このアカウントには、Device Run と 課金関連の呼び出しに必要なスコープがないことがよくあります （No service account scopes specified）。有効なアカウントがない場合、またはこのようなサービスアカウントしかない場合は、ユーザーにサインインを依頼してください。 --update-adc は同じ手順で Application Default Credentials も更新します。SSH またはリモートターミナルでは、 --no-launch-browser を追加してください。

   gcloud auth list --filter=status:ACTIVE --format="value(account)"
   gcloud auth login --update-adc
   

3. プロジェクト：ユーザーの有効なプロジェクト、またはユーザーが指定したプロジェクトを使用します。プロジェクトをハードコードせず、確認なしに有効なプロジェクトを変更しないでください。

   export PROJECT_ID=$(gcloud config get project)
   # ユーザーが切り替えを依頼した場合のみ：
   gcloud config set project PROJECT_ID
   

4. 課金：Device Run の料金はプロジェクトに請求されます。課金が有効になっていることを確認してください。有効でない場合は処理を中止し、ユーザーに伝えてください。

   gcloud billing projects describe "${PROJECT_ID}" \
     --format="value(billingEnabled)"
   

5. Device Run API を有効にする（まだ有効になっていない場合。先に確認してください）：

   gcloud services enable devicerun.googleapis.com --project="${PROJECT_ID}"
   

6. IAM ロール：ユーザーにはプロジェクトで roles/devicerun.admin、 roles/serviceusage.serviceUsageConsumer、roles/viewer が必要です。 別のプロジェクトのバケットから入力を読み取るには、DDP サービスエージェントにそのバケットで roles/storage.objectViewer を付与してください（ https://docs.cloud.google.com/developer-device-platform/device-run/share-storage.md.txt を参照）。

7. バケット：セッションでは、入力と出力を Cloud Storage に保存します。--bucket-name を指定しない場合、gcloud は gs://${PROJECT_ID}-devicerun を使用または作成します。プロジェクト ID に :、.、または google が含まれる場合、gcloud はそれらを -、-、elgoog に置き換えてから -devicerun を追加します。submit または describe の出力に表示される Result files の URI から、実際のバケットを確認してください。--bucket-name で明示的に指定するバケットは、すでに存在している必要があります。バケット名のみを渡してください（gs:// やパスは付けません）。gs://<bucket>/automation/ 内の入力と出力は、削除するか、Cloud Storage のライフサイクルルールによって期限切れになるまで保持され、その間はストレージ料金が発生します。

コアワークフロー

1. デバイスを選択します。 ユーザーは通常、販売時の名称（「Pixel 10」、「Galaxy S22」など）でデバイスを指定しますが、--device には frankel-36（コードネーム＋Android API レベル）のようなカタログ ID が必要です。 device_selection.md を参照して、最新のカタログから名前を ID に 解決してください。ID を記憶に頼って推測してはいけません。デバイスが複数の Android バージョンで提供されていて、ユーザーがバージョンを指定していない場合は、各バージョンを 列挙しておすすめを提示し、ユーザーに 1 つ、複数（それぞれ 1 ジョブ）またはすべてを 選んでもらってください。黙って選んではいけません。送信する前に、解決した ID、デバイス名、 Android バージョンをユーザーに提示し、ユーザーに代わって選択した項目（物理または仮想、 バリアント）も明示してください。

2. 入力を準備します。 --executable、--test、--target-app および --other-files-to-push の送信元は、gs:// パスまたはローカルパスを指定できます。ローカル ファイルは毎回、新しい automation/inputs/<timestamp>/ フォルダーに自動アップロードされるため、 実行ごとに変更されるファイル（スクリプト、新しくビルドしたバイナリ）にはローカルパスを 優先してください。大きく、繰り返し使うファイル（モデル、データセット）は一度バケットに アップロードし、gs:// パスで参照してください。

3. 費用を確認します。 ユーザーの明示的な確認が必要です。 Device Run セッションの費用は、 アクティブな Google Cloud プロジェクトに請求されます。送信する前に、プロジェクト （${PROJECT_ID}）、デバイス、ジョブ数、タイムアウトをユーザーに伝え、料金が発生することを 警告し、承認されるまで作業を停止してください。手順を説明するだけの場合や、ユーザー自身が コマンドを実行する場合でも、送信コマンドを提示するすべての回答に、この料金に関する 警告を含めてください。

4. 送信します。 送信タイプを選択します。

   • ネイティブ実行ファイルまたはシェルスクリプト： android_executable.md を参照してください。
   • インストルメンテーションテスト APK： instrumentation.md を参照してください。
   • デバイスごとに同じバイナリを複数の設定（異なるフラグ、入力、環境変数）で実行する場合： multi_config_runs.md を参照してください。

5. 完了を待ちます。 数分を超える実行では、--async を指定して送信し、 session_lifecycle.md に従ってください。

6. 結果を収集します。 results.md に従って、アーティファクトを ダウンロードし、デバイスに対応付けます。

7. 結果を報告します。 デバイスごとに 1 行で、デバイス ID、ジョブフォルダー（job-NNN）、 結果、主な出力、セッションフォルダーの gs:// パスを報告してください。失敗、タイムアウト、 キャンセルされたジョブは省略せず、明示してください。

ルール

• 必ずタイムアウトを設定してください。 --executable-timeout（または --instrumentation-timeout）のデフォルトは 5m で、有効範囲は 1m～3h です。 実行時間を見積もり、明示的に設定してください。
• 引数はカンマ区切りです。 --executable-args の各要素が1つの引数になります。 スペース区切りのコマンドラインを書き換えてください。値にカンマが含まれる場合は、 ^SEP^ のプレフィックスを使用してください（ android_executable.mdを参照）。
• 直接呼び出す場合、シェルは使用できません。 バイナリを --executable に指定すると シェルは使われません。export ではなく、--executable-env-vars で環境変数を設定してください。
• 共有入力を上書きしないでください。 DDP はジョブの開始時に入力を取得します。 保留中のセッションが使用している gs:// のスクリプトやバイナリは、決して上書きしないでください。 ローカルパス（自動アップロードされます）または実行ごとに固有の gs:// パスを使用してください。
• --labels でセッションにラベルを付けてください（例：purpose=smoke,build=1234）。 こうすると、後で簡単に見つけられます。
• 適切な間隔でポーリングしてください。 短い間隔でポーリングしないでください。30～60秒ごとに ポーリングし、進捗を報告してください（session_lifecycle.mdを参照）。
• 要求があればキャンセルしてください。 ユーザーが停止を希望した場合は、セッションをキャンセルし （session_lifecycle.mdを参照）、キャンセルしたことをユーザーに伝えてください。
• バッチジョブの実行にDevice Streaming API（devicestreaming.googleapis.com、 deviceSessions）を使用しないでください。これは対話型リース用です。

リファレンス一覧

• device_selection.md：「Pixel 10」などのデバイス名をカタログIDに対応付け、 OSバージョン、物理デバイスか仮想デバイスかを確認します。
• android_executable.md：フラグ、直接呼び出し、共有ライブラリ、 実行ファイルとしてのスクリプト。
• instrumentation.md：APKテスト、シャーディング、 テスト対象。
• session_lifecycle.md：同期と非同期、待機、詳細表示、キャンセル、 ステータスと結果の種類。
• results.md：バケットの構成、ジョブとデバイスの対応付け、 ログ。
• multi_config_runs.md：デバイスごとに複数の構成で同じバイナリを実行します。
• troubleshooting.md：よくある失敗。