准备工作

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

过程

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

   export ENABLED_INGEST_MODE=SPARK_LEGACY
   

2. 通过运行以下命令，在启动摄入作业之前设置以下环境变量:

   export IBM_LH_BEARER_TOKEN=<token>
   export IBM_LH_SPARK_JOB_ENDPOINT=https://<cpd_url>/v4/analytics_engines/<instance_id>/spark_applications
   export HMS_CLIENT_USER=lakehouse
   export HMS_CLIENT_PASSWORD=<instance secret>
   export SOURCE_S3_CREDS="AWS_ACCESS_KEY_ID=*******,AWS_SECRET_ACCESS_KEY=*******,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>"
   export TARGET_S3_CREDS="AWS_ACCESS_KEY_ID=*******,AWS_SECRET_ACCESS_KEY=*******,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>"
   export IBM_LH_SPARK_EXECUTOR_CORES=<value>
   export IBM_LH_SPARK_EXECUTOR_MEMORY=<value>
   export IBM_LH_SPARK_EXECUTOR_COUNT=<value>
   export IBM_LH_SPARK_DRIVER_CORES=<value>
   export IBM_LH_SPARK_DRIVER_MEMORY=<value>
   export INSTANCE_ID=<instance_id>
   export USE_NATIVE_SPARK=<true/false>
   export USE_EXTERNAL_SPARK=<true/false>
   export IBM_LH_URL=https://<lh_hostname>
   export IBM_LH_USER_BEARER_TOKEN=<token>
   

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

   表 1

   环境变量名称	描述
   IBM_LH_BEARER_TOKEN	授权不记名令牌。 更多信息，请参阅 https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey。 对于 USE_EXTERNAL_SPARK=true，应使用外部 Spark 引擎 API 密钥生成承载令牌。
   IBM_LH_SPARK_JOB_ENDPOINT	用于 CPD 的 Spark 应用程序 v4 端点和用于 SaaS的 v3 端点。 检索 SaaS Spark 端点：https://cloud.ibm.com/docs/AnalyticsEngine?topic=AnalyticsEngine-retrieve-endpoints-serverless
   HMS_CLIENT_USER	元数据服务客户端的用户。 SaaS Spark 实施使用 ibmlhapikey。
   HMS_CLIENT_PASSWORD	元数据服务客户端的密码。 对于 SaaS, 您可以使用已部署 watsonx.data 的云账户中名为 ibmlhapikey 的 API 密钥。
   SOURCE_S3_CREDS	S3 源文件存储凭证，格式为：“AWS_ACCESS_KEY_ID=<access_key>,AWS_SECRET_ACCESS_KEY=<secret_key>,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>”
   TARGET_S3_CREDS	S3 目标表存储的证书格式：“AWS_ACCESS_KEY_ID=<access_key>,AWS_SECRET_ACCESS_KEY=<secret_key>,ENDPOINT_URL=<endpoint_url>,AWS_REGION=<region>,BUCKET_NAME=<bucket_name>”
   IBM_LH_SPARK_EXECUTOR_CORES	执行核心的可选火花引擎配置设置。
   IBM_LH_SPARK_EXECUTOR_MEMORY	执行器内存的可选火花引擎配置设置。
   IBM_LH_SPARK_EXECUTOR_COUNT	执行器数量的可选火花引擎配置设置。
   IBM_LH_SPARK_DRIVER_CORES	用于驱动核的可选火花引擎配置设置。
   IBM_LH_SPARK_DRIVER_MEMORY	可选的火花发动机配置设置，供驾驶员记忆。
   INSTANCE_ID	确定独特的实例。 在 SaaS 环境中，CRN 是实例 ID。 这是一个强制性参数。
   USE_NATIVE_SPARK	如果使用本地 spark 进行摄取，该参数值必须为 true。 这是一个强制性参数。
   USE_EXTERNAL_SPARK	当使用外部火花进行摄取时，该参数值必须为 true。
   IBM_LH_URL	该参数仅在 USE_EXTERNAL_SPARK=true 时使用。 值为 https://<lh_hostname>。<lh_hostname> 是 watsonx.data 实例的主机名。
   IBM_LH_USER_BEARER_TOKEN	该参数仅在 USE_EXTERNAL_SPARK=true 时使用。 承载令牌应使用用户 API 密钥生成。 更多信息，请参阅 https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey。

3. 您可以使用简单命令行或配置文件来运行采集作业，以 2 方式采集数据。

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

      ibm-lh data-copy --source-data-files s3://path/to/file/or/folder \
      --target-table <catalog>.<schema>.<table> \
      --ingestion-engine-endpoint "hostname=<hostname>,port=<port>,type=spark" \
      --trust-store-password <truststore password> \
      --trust-store-path <truststore path> \
      --log-directory /tmp/mylogs \
      --partition-by "<columnname1>, <columnname2> \
      --target-catalog-uri 'thrift://<mds_thrift_uri>'
      

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

      表 2

      参数	描述
      --source-data-files	s3parquet 或 CSV 文件或文件夹的路径。 文件夹路径必须以 "/" 结尾。 文件名区分大小写。
      --target-table	目标表格式为 <catalogname>.<schemaname>.<tablename>。
      --log-directory	该选项用于指定日志文件的位置。
      --ingestion-engine-endpoint	摄取引擎端点的格式为 hostname=’’,port=’’,type=spark”。 类型必须设置为火花。
      --partition-by	该参数支持 partition-by 列表中时间戳的年、月、日、小时功能。 如果目标表已经存在或未提及 create-if-not-exist 参数，则分区-by 不会对数据产生任何影响。
      --trust-store-password	spark 作业 pod 内信任存储证书的密码。 CPD 和SaaS中 Spark 的当前密码为 changeit。
      --trust-store-path	火花任务 pod 中信任存储证书的路径。 目前 Spark 在 CPD 和SaaS领域的发展方向是 file:///opt/ibm/jdk/lib/security/cacerts。
      --target-catalog-uri	MDS 节俭终点。
      	SaaS endpoint example: thrift://<metastore_host_value>. <metastore_host_value> is taken from the details tab of the catalog in the Infrastructure page.
      --create-if-not-exist	如果未创建目标模式或表，请使用此选项。 如果目标模式或表已创建，请勿使用。
      --schema	使用该选项时，其值格式为 path/to/csvschema/config/file。 使用schema.cfg文件的路径，该文件指定 CSV 源文件或文件夹的页眉和分隔符值。

   2. 运行以下命令以从配置文件采集数据:

      ibm-lh data-copy --ingest-config /<your_ingest_configfilename>
      

      其中配置文件具有以下信息:

      [global-ingest-config]
      target-tables:<catalog>.<schema>.<table>
      ingestion-engine:hostname='',port='',type=spark
      create-if-not-exist:true/false
      
      [ingest-config1]
      source-files:s3://path/to/file/or/folder
      target-catalog-uri:thrift://<mds_thrift_uri>
      trust-store-path:<truststore path>
      trust-store-password:<truststore password>
      log-directory /tmp/mylogs
      partition-by "<columnname1>, <columnname2>
      schema:/path/to/csvschema/config/file [Optional]
      

      配置文件摄入作业中使用的参数列示如下:

      表 3

      参数	描述
      source-files	s3parquet 或 CSV 文件或文件夹的路径。 文件夹路径必须以"/"结尾
      target-table	目标表格式为 <catalogname>.<schemaname>.<tablename>。
      ingestion-engine	摄取引擎端点的格式为 hostname=’’, port=’’,type=spark”。 类型必须设置为火花。
      log-directory	该选项用于指定日志文件的位置。
      --partition-by	该参数支持 partition-by 列表中时间戳的年、月、日、小时功能。 如果目标表已经存在或未提及 create-if-not-exist 参数，则分区-by 不会对数据产生任何影响。
      trust-store-password	spark 作业 pod 内信任存储证书的密码。 CPD 和SaaS中 Spark 的当前密码为 changeit。
      trust-store-path	火花任务 pod 中信任存储证书的路径。 目前 Spark 在 CPD 和SaaS领域的发展方向是 file:///opt/ibm/jdk/lib/security/cacerts。
      target-catalog-uri	MDS 节俭终点。
      	CPD endpoint example: thrift://<metastore_host_value>. <metastore_host_value> is taken from the details tab of the catalog in the Infrastructure page.
      	SaaS endpoint example: thrift://<metastore_host_value>. <metastore_host_value> is taken from the details tab of the catalog in the Infrastructure page.
      create-if-not-exist	如果未创建目标模式或表，请使用此选项。 如果目标模式或表已创建，请勿使用。
      schema	使用该选项时，其值格式为 path/to/csvschema/config/file。 使用schema.cfg文件的路径，该文件指定 CSV 源文件或文件夹的页眉和分隔符值。

   处理表和架构名称中的特殊字符的能力受到底层引擎（Spark、Presto) 及其各自的特殊字符支持。

   • 常规语法：--target-tables <catalogname>.<schemaname>.<tablename>。
   • 带有特殊字符选项 1 的语法：--target-tables <catalogname>.<schemaname>."table\.name"。 使用此语法，转义字符 \ 在双引号内使用以转义句点 (.)。转义字符 \ 仅当表名中存在特殊字符句点（.）时使用。
   • 特殊字符选项 2 的语法：--target-tables <catalogname>.<schemaname>."'table.name'"。 使用此语法，句点（.）不会被转义，在使用额外的单引号时也不需要使用转义字符。