通过命令行输入数据 - Spark REST API

您可以运行 ibm-lh 工具，使用 IBM® watsonx.data REST API 通过命令行界面 (CLI) 将数据摄取到 IBM Analytics Engine 中。此基于 CLI 的摄入使用 REST 端点来执行摄入。这是缺省摄入方式。本主题中列出了用于运行摄入作业的命令。

准备工作

您必须在目录中具有管理员角色和特权才能通过 Web 控制台进行摄入。
添加并注册 IBM Analytics Engine (Spark)。请参见配置 Spark 引擎。
为目标目录添加存储器。请参阅添加存储目录对。
在目录中为要采集的数据创建模式和表。请参阅创建模式和创建表。

过程

通过运行以下命令，在启动摄入作业之前，将必需环境变量 ENABLED_INGEST_MODE 设置为 SPARK :
```
export ENABLED_INGEST_MODE=SPARK
```

通过运行以下命令，在启动摄入作业之前根据需要从以下位置设置可选环境变量:

export IBM_LH_SPARK_EXECUTOR_CORES=1
export IBM_LH_SPARK_EXECUTOR_MEMORY=2G
export IBM_LH_SPARK_EXECUTOR_COUNT=1
export IBM_LH_SPARK_DRIVER_CORES=1
export IBM_LH_SPARK_DRIVER_MEMORY=2G

如果 IBM Analytics Engine 上的 IBM Cloud Serverless 实例在 watsonx.data 上注册为外部 Spark，则 Spark 驱动程序、执行器 vCPU 和内存组合的比例必须为 1:2、1:4 或 1:8。请参见 Analytics Engine实例的默认限制和配额。

表 1
环境变量名称	描述
`IBM_LH_SPARK_EXECUTOR_CORES`	执行程序核心的可选 Spark 引擎配置设置
`IBM_LH_SPARK_EXECUTOR_MEMORY`	执行程序内存的可选 Spark 引擎配置设置
`IBM_LH_SPARK_EXECUTOR_COUNT`	执行程序计数的可选 Spark 引擎配置设置
`IBM_LH_SPARK_DRIVER_CORES`	驱动程序核心的可选 Spark 引擎配置设置
`IBM_LH_SPARK_DRIVER_MEMORY`	驱动程序内存的可选 Spark 引擎配置设置

运行以下命令以从单个或多个源数据文件采集数据:

ibm-lh data-copy --target-table iceberg_data.ice_schema.ytab \
--source-data-files "s3://lh-ingest/hive/warehouse/folder_ingestion/" \
--user someuser@us.ibm.com \
--password **** \
--url https://us-south.lakehouse.dev.cloud.ibm.com/ \
--instance-id crn:v1:staging:public:lakehouse:us-south:a/fd160ae2ce454503af0d051dfadf29f3:25fdad6d-1576-4d98-8768-7c31e2452597:: \
--schema /home/nz/config/schema.cfg \
--engine-id spark214 \
--log-directory /tmp/mylogs \
--partition-by "<columnname1>, <columnname2> \

其中使用的参数列示如下:

表 2
参数	描述
`--engine-id`	当使用基于 REST API 的 `SPARK` 接收时，Spark 引擎的引擎 id。
`--instance-id`	确定独特的实例。在SaaS环境中，CRN 是实例 ID。
`--log-directory`	该选项用于指定日志文件的位置。
`--partition-by`	该参数支持 `partition-by` 列表中时间戳的年、月、日、小时功能。如果目标表已经存在，则 `partition-by` 不会对数据产生任何影响。
`--password`	连接到实例的用户的密码。在SaaS,中使用的是该机构的 API 密钥。
`--schema`	使用该选项时，其值格式为 path/to/csvschema/config/file。使用schema.cfg文件的路径，该文件指定 CSV 源文件或文件夹的标题和分隔符值。
`--source-data-files`	s3parquet 或 CSV 文件或文件夹的路径。文件夹路径必须以 "/" 结尾。文件名区分大小写。
`--target-table`	目标表格式为 `<catalogname>.<schemaname>.<tablename>`。
`--user`	连接到实例的用户的用户名。
`--url`	IBM® watsonx.data集群位置的基本 URL。

ibm-lh data-copy returns the value 0 when ingestion job is completed successfully. 当摄取任务失败时，ibm-lh data-copy 返回一个非 0 值。

运行以下命令，获取采集作业的状态：

ibm-lh get-status --job-id <Job-id> --instance-id --url --user --password

其中使用的参数如下：

表3
参数	描述
`--job-id<Job id>`	当启动 REST API 或基于 UI 的提取时，会生成作业 ID。此作业 ID 用于获取摄取作业的状态。此参数仅用于 `ibm-lh get-status` 命令。此参数的简短命令是 `-j`。

运行以下命令可获取所有摄取作业的历史记录：

ibm-lh get-status --all-jobs --instance-id --url --user --password

其中使用的参数如下：

表4
参数	描述
`--all-jobs`	此 all-jobs 参数提供所有摄取作业的历史记录。此参数仅用于 `ibm-lh get-status` 命令。

get-status ibm-lh 仅支持交互式摄取模式。