存取 Airflow 指令列介面

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Apache Airflow 具有指令列介面 (CLI)，可用於執行觸發及管理 DAG、取得 DAG 執行和工作相關資訊，以及新增和刪除連線和使用者等工作。

支援的 Airflow CLI 指令

Airflow 使用 Airflow CLI 語法，相關說明請參閱 Airflow 說明文件。

Cloud Composer 3 支援下列 Airflow CLI 指令：

  • (Airflow 2 和 3) gcloud composer environments run 指令會為您的環境執行 Airflow CLI 指令。部分指令遭到封鎖，無法執行。如需支援的 Airflow CLI 指令清單，請參閱指令參考資料。

  • (Airflow 3) airflowctl 指令列工具支援部分 Airflow CLI 指令，並使用 Airflow REST API 執行這些指令。Cloud Composer 支援 airflowctl 中的所有指令。確認使用者的 Airflow 帳戶具有可執行特定指令的 Airflow 角色。

事前準備

如要透過 Google Cloud CLI 執行 Airflow CLI 指令，請按照下列步驟操作：

  • 您的 Google 帳戶必須具備權限，才能透過 Cloud Composer 使用 Google Cloud CLI，並執行 Airflow CLI 指令。

  • 透過 Google Cloud CLI 執行的 Airflow CLI 指令會耗用 environments.executeAirflowCommand 配額。

如要透過 airflowctl 指令列工具執行 Airflow CLI 指令 (適用於 Airflow 3)：

使用 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 環境中觸發名稱為 sample_quickstart 且 ID 為 5077 的 DAG，請使用以下指令：

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

使用 airflowctl 執行 Airflow CLI 指令

airflowctl 指令列工具是 Airflow 提供的指令列公用程式，可執行 Airflow CLI 指令。這項工具支援部分 Airflow CLI 指令，並使用 Airflow REST API 執行這些指令。Cloud Composer 支援 airflowctl 中的所有指令。

在 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 欄位包含記錄檔行。

如要取得指令執行狀態並擷取記錄，請提供 executionId、pod 和 podNamespace 值 (由 ExecuteAirflowCommandRequest 傳回)：

範例：

// 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
}

後續步驟