Airflow コマンドライン インターフェースにアクセスする

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Apache Airflow には、DAG のトリガーと管理、DAG 実行とタスクに関する情報の取得、接続とユーザーの追加と削除など、タスクの実行に使用できるコマンドライン インターフェース（CLI）があります。

サポートされている Airflow CLI コマンド

Airflow では、Airflow ドキュメントで説明されている Airflow CLI 構文を使用します。

Cloud Composer 3 は、次の Airflow CLI コマンドをサポートしています。

  • （Airflow 2 と 3） gcloud composer environments run コマンドは、環境の Airflow CLI コマンドを実行します。一部のコマンドはブロックされており、実行できません。サポートされている Airflow CLI コマンドの一覧については、コマンドのリファレンスをご覧ください。

  • （Airflow 3）airflowctl コマンドライン ツールは、Airflow CLI コマンドのサブセットをサポートし、Airflow REST API を使用して実行します。airflowctl で使用可能なすべてのコマンドは、Cloud Composer でサポートされています。ユーザーの Airflow アカウントに、特定のコマンドを実行できる Airflow ロールがあることを確認します。

始める前に

Google Cloud CLI を介して Airflow CLI コマンドを実行する場合:

  • Cloud Composer で Google Cloud CLI を使用して Airflow CLI コマンドを実行するには、Google アカウントに権限が必要です。

  • Google Cloud CLI を介して実行される Airflow CLI コマンドは、environments.executeAirflowCommand 割り当てを消費します。

airflowctl コマンドライン ツール（Airflow 3）で Airflow CLI コマンドを実行する場合:

gcloud CLI で Airflow CLI コマンドを実行する

環境で Airflow CLI コマンドを実行するには、gcloud CLI を使用します。

gcloud composer environments run ENVIRONMENT_NAME \
    --location LOCATION \
    SUBCOMMAND \
    -- SUBCOMMAND_ARGUMENTS

次のように置き換えます。

  • ENVIRONMENT_NAME: 環境の名前。
  • LOCATION: 環境が配置されているリージョン。
  • SUBCOMMAND: サポートされている Airflow CLI コマンドのいずれか。
  • SUBCOMMAND_ARGUMENTS は、Airflow CLI コマンドの引数に置き換えます。

サブコマンド引数の区切り文字

-- で、指定された Airflow CLI コマンドの引数を区切ります。

  • 複合 CLI コマンドをサブコマンドとして指定します。
  • 複合コマンドの引数は、-- 区切り文字の後にサブコマンド引数として指定します。

例:

gcloud composer environments run example-environment \
    dags list -- --output=json

デフォルトのロケーション

大部分の gcloud composer コマンドでは、ロケーションを指定する必要があります。ロケーションを指定するには、--location フラグを使用するか、デフォルトのロケーションを設定します。

たとえば、Cloud Composer 環境で ID 5077 を指定し、sample_quickstart という名前の DAG をトリガーするには、次のようにします。

gcloud composer environments run example-environment \
    --location us-central1 dags trigger -- sample_quickstart \
    --run-id=5077

airflowctl を使用して Airflow CLI コマンドを実行する

airflowctl コマンドライン ツールは、Airflow CLI コマンドを実行するために Airflow によって提供されるコマンドライン ユーティリティです。Airflow CLI コマンドのサブセットをサポートし、Airflow REST API を使用して実行します。airflowctl で使用可能なすべてのコマンドは、Cloud Composer でサポートされています。

Cloud Composer での airflowctl を使用した認可と認証は、次のように機能します。

  • airflowctl は Airflow REST API を使用するため、Google アカウントまたはサービス アカウントに関連付けられている Airflow ユーザー アカウントに、コマンドを実行するのに十分な権限を持つ Airflow ロールがあることを確認してください。たとえば、一部のコマンドは Admin ロールを持つ Airflow ユーザーのみが実行できます。

  • airflowctl で使用される API トークンは、gcloud auth コマンドで提供されます。デフォルトでは、トークンの有効期限は 1 時間です。このコマンドに指定された --lifetime 引数を使用して変更できます。

airflowctl で認証するには、次のコマンドを実行します。

airflowctl auth login \
  --api-url WEB_SERVER_URL \
  --api-token $(gcloud auth print-access-token)

次のように置き換えます。

例:

airflowctl auth login \
  --api-url https://example-dot-us-central1.composer.googleusercontent.com \
  --api-token $(gcloud auth print-access-token)

airflowctl で認証すると、Airflow CLI コマンドを実行できます。

airflowctl dags list

Cloud Composer API を使用して Airflow CLI コマンドを実行する

Cloud Composer 3 では、Cloud Composer API を使用して Airflow CLI コマンドを実行できます。

コマンドの実行

environments.executeAirflowCommand API リクエストを作成します。

{
  "environment": "projects/PROJECT_ID/locations/LOCATION/environments/ENVIRONMENT_NAME",
  "command": "AIRFLOW_COMMAND",
  "subcommand": "AIRFLOW_SUBCOMMAND",
  "parameters": [
    "SUBCOMMAND_PARAMETER"
  ]
}

以下を置き換えます。

  • PROJECT_ID: プロジェクト ID
  • LOCATION: 環境が配置されているリージョン。
  • ENVIRONMENT_NAME: 環境の名前。
  • AIRFLOW_COMMAND: 実行する Airflow CLI コマンド（dags など）。
  • AIRFLOW_SUBCOMMAND: 実行する Airflow CLI コマンドのサブコマンド（list など）。
  • （省略可）SUBCOMMAND_PARAMETER: サブコマンドのパラメータ。複数のパラメータを使用する場合は、リストにアイテムを追加します。

例:

// POST https://composer.googleapis.com/v1/{environment=projects/*/locations/*/environments/*}:executeAirflowCommand
{
  "environment": "projects/example-project/locations/us-central1/environments/example-environment",
  "command": "dags",
  "subcommand": "list",
  "parameters": [
    "-o json",
    "--verbose"
  ]
}

ポーリング コマンドのステータス

Cloud Composer API を使用して Airflow CLI コマンドを実行した後、PollAirflowCommand リクエストを発行し、エラーとステータス コード用の　exitInfo のフィールドを調べて、コマンドが正常に完了したかどうかを確認します。output フィールドにはログ行が含まれます。

コマンドの実行ステータスを取得してログを取得するには、ExecuteAirflowCommandRequest から返された executionId、pod、podNamespace の値を指定します。

例:

// POST https://composer.googleapis.com/v1/{environment=projects/*/locations/*/environments/*}:pollAirflowCommand
{
  "executionId": "a117da94-355d-4ad4-839e-ac39ccb0bf48",
  "pod": "airflow-webserver-66d96b858f-tn96b",
  "podNamespace": "airflow-2-10-2-build-13-226523e4",
  "nextLineNumber": 1
}

次のステップ