volc-flink-cli 1.0.0__tar.gz

volc_flink_cli-1.0.0/PKG-INFO

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: volc-flink-cli
+Version: 1.0.0
+Summary: Volcano Engine Flink Stream Computing Python Client CLI
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.0.0
+Requires-Dist: volcengine-python-sdk>=5.0.0
+Requires-Dist: tos>=2.9.0
+
+# 火山引擎流式计算 Flink 版 CLI / Python SDK
+
+面向火山引擎流式计算 Flink 版的命令行工具与 Python SDK（非官方），覆盖登录认证、项目/资源池、草稿（SQL/JAR）、任务运维、日志与事件、Catalog 元数据、Session 集群等常用能力。
+
+## 目录
+
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [常用场景](#常用场景)
+  - [草稿（Drafts）](#草稿drafts)
+  - [任务（Jobs）](#任务jobs)
+  - [监控（Monitor）](#监控monitor)
+  - [Catalog（元数据）](#catalog元数据)
+  - [Sessions（Session 集群）](#sessionssession-集群)
+- [配置与安全](#配置与安全)
+- [Python API](#python-api)
+- [开发说明](#开发说明)
+- [常见问题](#常见问题)
+
+## 安装
+
+### 环境要求
+
+- Python 3.7+
+
+### 安装方式
+
+```bash
+pip install .
+```
+
+开发模式（可编辑安装）：
+
+```bash
+pip install -e .
+```
+
+安装完成后获得命令：`volc_flink`。
+
+## 快速开始
+
+### 1）登录
+
+```bash
+volc_flink login --region cn-beijing
+```
+
+### 2）选定项目（推荐）
+
+先列举项目：
+
+```bash
+volc_flink projects list
+```
+
+设置默认项目（之后大部分命令可省略 `-p/--project` 或 `--project-id`）：
+
+```bash
+volc_flink config set-default-project --project-id YOUR_PROJECT_ID
+```
+
+也可以按项目名设置：
+
+```bash
+volc_flink config set-default-project --name YOUR_PROJECT_NAME
+```
+
+### 3）查看帮助
+
+```bash
+volc_flink --help
+volc_flink drafts --help
+volc_flink jobs --help
+```
+
+## 常用场景
+
+### 草稿（Drafts）
+
+#### 1）列目录 / 列草稿
+
+列草稿目录（用于创建草稿时选择目录）：
+
+```bash
+volc_flink drafts dirs
+```
+
+列草稿（用于查询草稿 ID、类型、目录等）：
+
+```bash
+volc_flink drafts apps --directory "/a/b/c"
+```
+
+兼容命令（等价于 `drafts apps`）：
+
+```bash
+volc_flink drafts list --directory "/a/b/c"
+```
+
+#### 2）校验 SQL 草稿（Validate）
+
+说明：Validate 不只做语法解析，也可能会触发 connector/catalog 的校验，因此失败不一定是 SQL 语法错误。
+
+```bash
+# 通过草稿 ID 校验
+volc_flink drafts validate --draft-id YOUR_DRAFT_ID
+
+# 通过草稿名称或路径校验（自动解析草稿ID）
+volc_flink drafts validate --draft "my_draft"
+volc_flink drafts validate --draft "/a/b/c/my_draft.sql"
+```
+
+#### 3）创建草稿（SQL）
+
+```bash
+volc_flink drafts create \
+  --name "test-streaming-sql" \
+  --directory "/a/b/c" \
+  --job-type FLINK_STREAMING_SQL \
+  --engine-version FLINK_VERSION_1_17 \
+  --sql "SELECT 1;"
+```
+
+#### 4）创建草稿（JAR：本地上传到 TOS）
+
+```bash
+volc_flink drafts create \
+  --name "test-batch-jar" \
+  --directory "/a/b/c" \
+  --job-type FLINK_BATCH_JAR \
+  --engine-version FLINK_VERSION_1_20 \
+  --jar-path ./examples/jar/WordCount-flink-1-20.jar \
+  --main-class org.apache.flink.streaming.examples.wordcount.WordCount
+```
+
+#### 5）依赖与动态参数
+
+Dependency 字段为 JSON 字符串，例如：
+
+```json
+{"jars":["tos://flink-cwz-paimon/flink-client/resrouce/jars/WordCount-flink-1-20.jar"]}
+```
+
+给草稿添加依赖（支持 tos 路径或本地路径，本地会自动上传并输出 `tos://...` 路径）：
+
+```bash
+volc_flink drafts dependency add \
+  --draft "/a/b/c/jar_job" \
+  --jar tos://YOUR_BUCKET/path/to/jars/dep1.jar \
+  --jar ./path/to/dep2.jar
+```
+
+动态参数（DynamicOptions）为 String-String KV JSON，例如：
+
+```json
+{"parallelism.default":"4","taskmanager.numberOfTaskSlots":"4"}
+```
+
+设置/删除动态参数：
+
+```bash
+volc_flink drafts params set --draft "/a/b/c/jar_job" --kv parallelism.default=4
+volc_flink drafts params unset --draft "/a/b/c/jar_job" --key parallelism.default
+```
+
+#### 6）更新与发布
+
+更新 SQL：
+
+```bash
+volc_flink drafts update --draft "/a/b/c/sql_job" --sql-file /path/to/job.sql
+```
+
+发布草稿：
+
+```bash
+volc_flink drafts publish --draft "/a/b/c/sql_job" --resource-pool YOUR_RESOURCE_POOL_NAME
+```
+
+### 任务（Jobs）
+
+列举任务与详情：
+
+```bash
+volc_flink jobs list
+volc_flink jobs detail --job-id YOUR_JOB_ID
+```
+
+查询任务运行记录/事件：
+
+```bash
+volc_flink jobs instances --job-id YOUR_JOB_ID --limit 20
+volc_flink jobs events --job-id YOUR_JOB_ID --limit 50
+```
+
+启动/停止/重启（支持 `--inspect` 轮询状态）：
+
+```bash
+volc_flink jobs start --job-id YOUR_JOB_ID --inspect --timeout 300
+volc_flink jobs stop --job-id YOUR_JOB_ID --inspect --timeout 300
+volc_flink jobs restart --job-id YOUR_JOB_ID --inspect --timeout 300
+```
+
+Rescale（调整规格并自动发布重启）：
+
+```bash
+volc_flink jobs rescale --job-id YOUR_JOB_ID --parallelism 32 --tm-spec 4C16GB --tm-slots 4 --jm-spec 2C8GB --inspect --timeout 300
+```
+
+### 监控（Monitor）
+
+查询事件：
+
+```bash
+volc_flink monitor events --job-id YOUR_JOB_ID --limit 50
+```
+
+查询日志（默认选择最新实例，支持时间范围、cursor、tail）：
+
+```bash
+volc_flink monitor logs --job-id YOUR_JOB_ID --level ERROR --since "2025-01-01 12:00:00" --until "2025-01-01 13:00:00"
+volc_flink monitor logs --job-id YOUR_JOB_ID --follow --interval 2
+volc_flink monitor logs --job-id YOUR_JOB_ID --cursor YOUR_CURSOR
+```
+
+查询 FlinkUI：
+
+```bash
+volc_flink monitor flinkui url --job-id YOUR_JOB_ID
+volc_flink monitor flinkui overview --job-id YOUR_JOB_ID
+volc_flink monitor flinkui exceptions --job-id YOUR_JOB_ID
+```
+
+### Catalog（元数据）
+
+列出 Catalog 列表：
+
+```bash
+volc_flink catalog tree
+```
+
+展开某个 Catalog（以列表形式列出该 Catalog 下的 Database）：
+
+```bash
+volc_flink catalog tree --catalog-id 45
+```
+
+展开某个 Database（列出 Table）：
+
+```bash
+volc_flink catalog tree --catalog-id 45 --database test_db
+```
+
+查看详细信息：
+
+```bash
+volc_flink catalog catalogs list
+volc_flink catalog catalogs show --catalog-id 45
+volc_flink catalog databases show --catalog-id 45 --database test_db
+volc_flink catalog tables show --catalog-id 45 --database test_db --table prds_pk1
+```
+
+### Sessions（Session 集群）
+
+列举 Session 集群：
+
+```bash
+volc_flink sessions list
+```
+
+创建 Session 集群：
+
+```bash
+volc_flink sessions create \
+  --name "abcdef" \
+  --resource-pool "cwz-test" \
+  --queue "o-00c004d6dape" \
+  --engine-version "FLINK_VERSION_1_20" \
+  --context "DEBUG" \
+  --tm-min 1 --tm-max 10 \
+  --tm-vcore 2 --tm-memory 8 \
+  --slots-per-tm 2 \
+  --jm-vcore 1 --jm-memory 4
+```
+
+启动/停止：
+
+```bash
+volc_flink sessions start --id YOUR_SESSION_ID
+volc_flink sessions stop --id YOUR_SESSION_ID
+```
+
+获取 FlinkUI（工具会自动获取 token 并通过网关拼接 URL）：
+
+```bash
+volc_flink sessions ui --id YOUR_SESSION_ID
+```
+
+## 配置与安全
+
+### 配置文件位置
+
+- Windows：`C:\Users\YourUsername\.volcano_flink\credentials.json`
+- Linux/macOS：`~/.volcano_flink/credentials.json`
+
+### 安全说明
+
+- 密钥信息存储在用户本地目录，文件权限设置为仅当前用户可读写（0600）
+- 建议定期更换访问密钥
+- 生产环境建议使用更安全的密钥管理方案
+
+## Python API
+
+```python
+from volcano_flink_client.auth.auth import AuthManager
+from volcano_flink_client.api import ApiClient
+from volcano_flink_client.projects.projects import ProjectManager
+
+auth_manager = AuthManager()
+credentials = auth_manager.login(access_key="YOUR_AK", secret_key="YOUR_SK", region="cn-beijing")
+api_client = ApiClient(credentials)
+
+project_manager = ProjectManager(api_client)
+projects = project_manager.list_projects()
+for p in projects:
+    print(p.name, p.id)
+```
+
+## 开发说明
+
+### 代码结构
+
+```
+volcano_flink_client/
+├── api.py               # HTTP 请求与签名
+├── auth/                # 认证管理
+├── projects/            # 项目操作
+├── resource_pools/      # 资源池操作
+├── drafts/              # 草稿操作
+├── jobs/                # 任务操作
+├── catalogs/            # Catalog 元数据
+└── sessions/            # Session 集群
+```
+
+### 本地验证
+
+```bash
+python integration_test.py
+```
+
+## 常见问题
+
+### Q：如何获取 AK/SK？
+
+进入火山引擎控制台的访问控制页面创建与管理访问密钥：<https://console.volcengine.com/iam/accesskey/>
+
+### Q：命令忘了怎么用？
+
+```bash
+volc_flink --help
+volc_flink <module> --help
+volc_flink <module> <cmd> --help
+```
+
+### Q：登录失败怎么办？
+
+- 确认 AK/SK 正确
+- 确认网络可访问火山引擎 OpenAPI
+- 确认账号具备对应权限