Controlplane Module ZH

English version

控制平面模組 — beam_pipeline_toolkit/controlplane/

通用的 Dataflow 控制平面 API：提交任務、請求取消任務、讀取任務證據。全部透過 REST 呼叫、皆使用 ADC 驗證，絕不透過 gcloud 子行程。

google_auth_client.py

get_authorized_session() — 延遲匯入的 ADC(google.auth.default())+ AuthorizedSession。失敗時拋出 CloudAccessError。此套件內其他模組的 HTTP session 都來自這裡。

dataflow_submit.py

• submit_job(*, gate_check, submit_fn) — 先執行 gate_check()(失敗即拋出例外)，再執行 submit_fn()；任何失敗都會包裝成 CloudSubmissionUnavailable，避免函式庫內部細節外洩到呼叫端的 API 層。
• generate_job_name(prefix) — <prefix>-<UTC 時間戳記>-<隨機十六進位後綴>，只使用 Dataflow 任務名稱合法的字元。這是選用的便利工具。

dataflow_stop.py

request_job_cancellation(*, project, job_id, region) — 對 projects.locations.jobs.update發出 PUT，帶上 requestedState: JOB_STATE_CANCELLED。回傳請求後立即回報的狀態(通常是 CANCELLING——取消是非同步的)。

dataflow_evidence.py

僅唯讀(GET)——這裡完全不會提交、取消、drain 或更新任何任務。

• get_dataflow_job_summary(...) → DataflowJobSummary(名稱、短 id、地區、類型、狀態、時間戳記、console URL)。
• get_dataflow_job_metrics(...) → 每個請求的 counter 名稱對應一個 DataflowCounterValue；在真實回應中找不到的一律回報 found=False，絕不捏造。
• is_job_running(...) → 只有狀態為 RUNNING 時才回傳 True。
• extract_user_counter(...) — 從原始的 .../metrics JSON 回應中取出一個指定名稱的使用者命名空間 counter 純量值。
• job_url/console_url — REST/console URL 產生器。

若需要更完整的營運視角，可搭配自己以 BigQuery 為後端的證據查詢——此模組只知道 Dataflow REST API 本身回報的內容。