SFTP

通过 SFTP 连接器，您可以连接到 SFTP 服务器并执行文件传输操作。

准备工作

在 Google Cloud 项目中，执行以下任务：

  • 确保已设置网络连接。如需了解相关信息，请参阅网络连接。
  • 向配置连接器的用户授予 roles/connectors.admin IAM 角色。
  • 向您要用于连接器的服务账号授予 roles/secretmanager.viewer 和 roles/secretmanager.secretAccessor IAM 角色
  • 启用 secretmanager.googleapis.com (Secret Manager API) 和 connectors.googleapis.com (Connectors API)。 如需了解详情，请参阅启用服务。

创建 SFTP 连接

一个连接需专用于一个数据源。这意味着，如果您有许多数据源，则必须为每个数据源创建单独的连接。如需创建连接，请执行以下操作：

  1. 在 Cloud 控制台 中，进入 Integration Connectors > 连接页面，然后选择或创建一个 Google Cloud 项目。

    转到“连接”页面

  2. 点击 + 新建以打开创建连接页面。
  3. 在位置部分中，从区域列表中选择一个位置，然后点击下一步。

    如需查看所有受支持区域的列表，请参阅位置。

  4. 在连接详情部分中，完成以下操作：
    1. 在连接器字段中，选择 SFTP。
    2. 在连接器版本字段中，选择所需的版本。
    3. 在连接名称字段中，输入连接实例的名称。连接名称可以包含小写字母、数字或连字符。名称必须以字母开头，以字母或数字结尾，且不得超过 49 个字符。
    4. （可选）输入连接实例的说明。
    5. 您可以选择启用 Cloud Logging，然后选择日志级别。默认情况下，日志级别设置为 Error。
    6. 在服务账号字段中，选择具有所需角色的账号。
    7. （可选）配置连接节点设置。
      • 节点数下限：输入连接节点数下限。
      • 节点数上限：输入连接节点数上限。

      节点是处理事务的连接单元（或副本）。 连接处理越多事务就需要越多节点，相反，处理越少事务需要越少节点。 如需了解节点如何影响连接器价格，请参阅 连接节点的价格。如果未输入任何值，则默认情况下，节点数下限设置为 2（以便提高可用性），节点数上限设置为 50。
    8. （可选）在远程路径字段中，输入 SFTP 服务器中要执行实体操作的文件夹路径，例如 List、Create、Update 或 Delete。

      9. 如果您要访问根文件夹中的实体（文件或文件夹）或根文件夹的直接子文件夹，则无需为此字段设置任何值。 不过，如果您想访问位于根文件夹以下 2 级或更深层级的嵌套实体，则必须将此字段的值设置为包含您要访问的实体的文件夹的基本路径。例如，如果您想访问 /folder_A/folder_B/folder_C/test.png 文件，则必须将“远程路径”设置为 /folder_A/folder_B/folder_C。

    9. （可选）点击 + 添加标签，以键值对的形式向连接添加标签。
    10. 点击下一步。
  5. 在目标部分中，输入要连接到的远程主机（后端系统）的详细信息，然后点击下一步。

    6. 在目标类型字段中，选择所需的类型：

    • 如需指定目标主机名或 IP 地址，请选择主机地址，然后在主机 1 字段中输入相应地址。
    • 如需建立专用连接，请选择端点连接，然后从端点连接列表中选择所需的连接。

    如果要与后端系统建立公共连接以提高安全性，您可以考虑为连接配置静态出站 IP 地址，然后将防火墙规则配置为仅将特定静态 IP 地址列入许可名单。
  6. 在身份验证部分中，选择身份验证类型，然后输入相关详细信息并点击下一步。

    SFTP 连接支持以下身份验证类型：

    • 用户名和密码
    • SSH_PUBLIC_KEY

    如需了解如何配置这些身份验证类型，请参阅配置身份验证。

  7. 查看您的连接和身份验证详细信息，然后点击创建。

配置身份验证

根据您要使用的身份验证输入详细信息。

  • 用户名和密码
    • 用户名：用于连接的 SFTP 用户名。
    • 密码：包含与 SFTP 用户名关联的密码的 Secret Manager Secret。
  • SSH_PUBLIC_KEY
    • 用户名：用于进行身份验证的 SFTP 用户账号。
    • SSH 私钥：用于 SSH 身份验证的私钥。
    • SSH 私钥密码：保护私钥（如果有）的口令/密码。
    • SSH 私钥类型：私钥的格式。

在集成中使用 SFTP 连接

创建连接后，该连接将在 Apigee Integration 和 Application Integration 中可用。您可以通过连接器任务在集成中使用该连接。

  • 如需了解如何在 Apigee Integration 中创建和使用连接器任务，请参阅连接器任务。
  • 如需了解如何在 Application Integration 中创建和使用连接器任务，请参阅连接器任务。

操作

本部分列出了连接器支持的部分操作。如需了解如何配置操作，请参阅操作示例。

上传操作

下表介绍了 Upload 操作的输入参数。

参数名称 数据类型 必需 说明
内容 字符串 否 要以文件形式上传的内容。
ContentBytes 字符串 否 要上传为文件的字节内容（以 Base64 字符串形式表示）。使用此方法上传二进制数据。
HasBytes 布尔值 否 指定内容是否应以字节形式上传。默认值为 false。
RemoteFile 字符串 是 远程主机上的文件名。
覆盖 布尔值 否 指定是否应覆盖远程文件。默认值为 false。

如需查看有关如何配置 Upload 操作的示例，请参阅示例。

下载操作

下表介绍了 Download 操作的输入参数。

参数名称 数据类型 必需 说明
RemoteFile 字符串 是 远程主机上的文件名。
HasBytes 布尔值 否 指定内容是否应以字节形式下载。默认值为 false。

如需查看有关如何配置 Download 操作的示例，请参阅示例。

MoveFile 操作

下表介绍了 MoveFile 操作的输入参数。

参数名称 数据类型 必需 说明
RemoteFile 字符串 是 要移动的远程文件的路径。
DestinationPath 字符串 是 您要将文件移到的新路径。

如需查看有关如何配置 MoveFile 操作的示例，请参阅示例。

RenameFile 操作

下表介绍了 RenameFile 操作的输入参数。

参数名称 数据类型 必需 说明
RemoteFile 字符串 是 要重命名的远程文件路径和名称。
NewFileName 字符串 是 远程文件的新名称。

如需查看有关如何配置 RenameFile 操作的示例，请参阅示例。

示例

本部分介绍如何在此连接器中执行一些实体操作和动作。这些示例描述了以下操作：

  • 列出根目录中的所有文件：
  • 列出与目录中的模式匹配的文件
  • 移动文件
  • 重命名文件
  • 删除文件
  • 上传 ASCII 文本文件
  • 上传二进制文件
  • 下载 ASCII 文本文件
  • 下载二进制文件
  • 下载多个文件

下表列出了连接器任务中的示例场景和相应的配置：

任务 示例命令 配置
列出根目录中的所有文件： ls /
  1. 在 Configure connector task 对话框中，点击 Entities。
  2. 选择 Root 实体，然后选择 List 操作。
  3. 点击完成。
列出目录中的 .csv 文件 ls /tmp/*.csv
  1. 在 Configure connector task 对话框中，点击 Entities。
  2. 从 Entity 列表中选择基本目录 (/tmp)。
  3. 选择 List 操作，然后点击完成。
  4. 设置过滤条件子句。如需设置子句，请在连接器任务的任务输入部分，点击 filterClause，然后在默认值字段中输入 FilePath LIKE '/tmp/%.csv'。
移动文件 mv /tmp/dir_A/hello_world.txt /dir_B/dir_C/
  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 MoveFile 操作，然后点击完成。
  3. 在连接器任务的任务输入部分中，点击 connectorInputPayload，然后在 Default Value 字段中输入类似于以下内容的值：
    {
"RemoteFile": "/tmp/dir_A/hello_world.txt",
"DestinationPath": "/dir_B/dir_C/"
}

此示例将 /tmp/dir_A/hello_world.txt 文件移动到 /dir_B/dir_C/ 目录。运行此示例后，连接器任务的 connectorOutputPayload 输出变量中会返回类似于以下内容的响应：

[{
"Success":"true"
}]
重命名文件 mv /tmp/hello_world.txt /tmp/hello_world_new.txt
  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 RenameFile 操作，然后点击完成。
  3. 在连接器任务的任务输入部分中，点击 connectorInputPayload，然后在 Default Value 字段中输入类似于以下内容的值：
    {
"RemoteFile": "/tmp/hello_world.txt",
"NewFilename": "hello_world_new.txt"
}

此示例将 hello_world.txt 文件重命名为 hello_world_new.txt。运行此示例后，连接器任务的 connectorOutputPayload 输出变量中会返回类似于以下内容的响应：

[{
"Success":"true"
}]
删除文件 rm /tmp/myfile.csv
  1. 在 Configure connector task 对话框中，点击 Entities。
  2. 从 Entity 列表中，选择包含要移动的文件的基本目录。
  3. 选择 Delete 操作，然后点击完成。
  4. 将实体 ID 设置为文件的完整路径。如需设置实体 ID，请在连接器任务的任务输入部分，点击 entityId，然后在默认值字段中输入 /tmp/myfile.csv。

    或者，您也可以将 filterClause 设置为 FilePath LIKE '/tmp/myfile.csv'，而不是指定 entityId。
上传 ASCII 文本文件 put file_1.txt /tmp/file_1.txt
  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 Upload 操作，然后点击完成。
  3. 在连接器任务的任务输入部分，点击 connectorInputPayload，然后在 Default Value 字段中输入以下内容：
    {
  "Content": "This is a sample text!\r\n",
  "RemoteFile": "/tmp/file_1.txt",
  "Overwrite": true
}

    4. 此示例会创建一个 file_1.txt 文件，该文件包含 SFTP 服务器的 /tmp 目录中的内容 This is a sample text!。由于 Overwrite 特性值为 true，因此同名的所有现有文件都会予以覆盖。

    设置 Overwrite 特性是可选的；默认情况下，值为 false。
上传二进制文件 put image_1.png /tmp/image_1.png 如需上传二进制内容，您必须先以 Base64 格式对内容进行编码。您可以选择一个工具来对内容进行编码。对内容进行编码的步骤不在本文档的讨论范围内。具有 Base64 字符串内容后，请执行以下步骤：
  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 Upload 操作，然后点击完成。
  3. 在连接器任务的任务输入部分，点击 connectorInputPayload，然后在 Default Value 字段中输入以下内容：
    {
  "ContentBytes": "SGVsbG8gd29ybGQ=",
  "RemoteFile": "/tmp/image_1.png",
  "Overwrite": true,
  "HasBytes": true
}

    4. 此示例使用 ContentBytes 字段中指定的内容创建 image_1.png 文件。该文件是在 SFTP 服务器的 /tmp 目录中创建。由于 Overwrite 特性值为 true，因此同名的所有现有文件都会予以覆盖。

    设置 Overwrite 特性是可选的；默认情况下，值为 false。
下载 ASCII 文本文件 get /tmp/myfile.txt
  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 Download 操作，然后点击完成。
  3. 在连接器任务的任务输出部分，点击 connectorInputPayload，然后在 Default Value 字段中输入以下内容：
    {
"RemoteFile": "/tmp/myfile.txt"
}

下载文件的内容以字符串形式显示在连接器任务的 connectorOutputPayload 响应参数的 Content 字段中。
下载二进制文件 get /tmp/myfile.png
  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 Download 操作，然后点击完成。
  3. 在连接器任务的任务输出部分，点击 connectorInputPayload，然后在 Default Value 字段中输入以下内容：
    {
"RemoteFile": "/tmp/myfile.png",
"HasBytes" : true
}

下载文件的内容以 Base64 编码的字符串形式显示在连接器任务的 connectorOutputPayload 响应参数的 ContentBytes 字段中。
下载多个文件
  1. 在 Configure connector task 对话框中，点击 Actions。
  2. 选择 Download 操作，然后点击完成。
  3. 在连接器任务的任务输出部分，点击 connectorInputPayload，然后在 Default Value 字段中输入以下内容：
    {
"RemoteFile": "/tmp/myfile*.txt"
}

系统限制

SFTP 连接器每秒每个节点可处理 1 个事务，并会限制超出此限制的任何事务。默认情况下，Integration Connectors 会为连接分配 2 个节点（以提高可用性）。

如需了解适用于 Integration Connectors 的限制，请参阅限制。

使用 Terraform 创建连接

您可以使用 Terraform 资源创建新连接。

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。

如需查看用于创建连接的 Terraform 模板示例，请参阅模板示例。

使用 Terraform 创建此连接时，您必须在 Terraform 配置文件中设置以下变量：

参数名称 数据类型 必需 说明
remote_path STRING 错误 SFTP 服务器中的当前路径。

载荷的 JSON 架构

SFTP 连接中的所有实体对象都具有预定义的 JSON 架构。 SFTP 连接中的实体对象使用以下 JSON 架构：

    {
      "type": "object",
      "properties": {
        "FilePath": {
          "type": "string",
          "readOnly": false
        },
        "Filename": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": false,
          "description": "The name of the file or directory."
        },
        "FileSize": {
          "type": [
            "number",
            "null"
          ],
          "readOnly": false,
          "description": "The size of the file."
        },
        "LastModified": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": false
        },
        "IsDirectory": {
          "type": [
            "boolean",
            "null"
          ],
          "readOnly": false
        },
        "Permissions": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": false
        },
        "Owner": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": false
        },
        "OwnerId": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": false
        },
        "Group": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": false
        },
        "GroupId": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": false
        }
      }
    }

向 Google Cloud 社区寻求帮助

您可以在 Google Cloud 社区的 Cloud 论坛中发布您的问题以及讨论此连接器。

后续步骤