安全檔案傳輸通訊協定

您可以使用 SFTP 連接器連線至 SFTP 伺服器,並執行檔案傳輸作業。

事前準備

在 Google Cloud 專案中,執行下列工作:

  • 確認已設定網路連線。詳情請參閱「網路連線」。
  • roles/connectors.admin IAM 角色授予設定連線器的使用者。
  • roles/secretmanager.viewerroles/secretmanager.secretAccessor 身分與存取權管理角色授予要用於連接器的服務帳戶
  • 啟用 secretmanager.googleapis.com (Secret Manager API) 和 connectors.googleapis.com (Connectors API)。 詳情請參閱「啟用服務」。

建立 SFTP 連線

連線專屬於資料來源。也就是說,如果您有多個資料來源,則必須為每個資料來源建立個別的連線。如要建立連線,請按照下列步驟操作:

  1. Cloud 控制台中,前往「Integration Connectors」>「Connections」頁面,然後選取或建立 Google Cloud 專案。

    前往「連線」頁面

  2. 按一下「+ 建立新項目」開啟「建立連線」頁面。
  3. 在「地區」部分中,從「區域」清單選取位置,然後按一下「下一步」

    如需所有支援的地區清單,請參閱「位置」一文。

  4. 在「連線詳細資料」部分,完成下列步驟:
    1. 在「連接器」欄位中,選取「SFTP」
    2. 在「連接器版本」欄位中,選取所需版本。
    3. 在「連線名稱」欄位中,輸入連線執行個體的名稱。連線名稱可包含小寫英文字母、數字或連字號,名稱開頭須為英文字母,結尾須為英文字母或數字,且不得超過 49 個字元。
    4. 視需要輸入連線執行個體的「Description」(說明)
    5. 或者,可啟用 Cloud Logging,然後選取記錄層級。記錄層級預設為 Error
    6. 在「服務帳戶」欄位中,選取具備必要角色的帳戶。
    7. (選用) 設定連線節點設定
      • 節點數量下限:輸入連線節點數量下限。
      • 節點數量上限:輸入連線節點數量上限。

      節點是用來處理交易的連線單位 (或備用資源)。如要處理更多連線交易,就需要更多節點;反之,如要處理較少的交易,則需要較少的節點。如要瞭解節點對連線器定價的影響,請參閱「 連線節點定價」。如未輸入任何值,系統預設會將節點下限設為 2 (提高可用性),節點上限則設為 50。

    8. (選用) 在「遠端路徑」欄位中,輸入 SFTP 伺服器中的資料夾路徑,以執行實體作業, 例如 ListCreateUpdateDelete
    9. 如果您要存取根資料夾中的實體 (檔案或資料夾),或是根資料夾的直接子資料夾,則不需要為這個欄位設定任何值。不過,如要存取位於根資料夾 2 個以上層級的巢狀實體,您必須將這個欄位的值設為含有要存取實體的資料夾基本路徑。舉例來說,如要存取 /folder_A/folder_B/folder_C/test.png 檔案,必須將遠端路徑設為 /folder_A/folder_B/folder_C

    10. (選用) 按一下「+ 新增標籤」,以鍵/值組合的形式為連線新增標籤。
    11. 點選「下一步」
  5. 在「目的地」部分,輸入要連線的遠端主機 (後端系統) 詳細資料,然後按一下「下一步」
  6. 在「目的地類型」欄位中,選取所需類型:

    • 如要指定目的地主機名稱或 IP 位址,請選取「主機地址」,然後在「主機 1」欄位中輸入地址。
    • 如要建立私人連線,請選取「Endpoint attachment」(端點連結),然後從「Endpoint Attachment」(端點連結) 清單中選擇所需連結。

    如要建立與後端系統的公開連線,並加強安全性,建議為連線設定靜態輸出 IP 位址,然後設定防火牆規則,只允許特定靜態 IP 位址。

  7. 在「驗證」部分,選取「驗證類型」, 然後輸入相關詳細資料,並按一下「下一步」

    SFTP 連線支援下列驗證類型:

    • 使用者名稱和密碼
    • SSH_PUBLIC_KEY

    如要瞭解如何設定這些驗證類型,請參閱「設定驗證」。

  8. 查看連線和驗證詳細資料,然後按一下「建立」

設定驗證機制

根據要使用的驗證方式輸入詳細資料。

  • 使用者名稱和密碼
    • 使用者名稱:用於連線的 SFTP 使用者名稱。
    • 密碼:Secret Manager 密鑰,內含與 SFTP 使用者名稱相關聯的密碼。
  • 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. 設定篩選器子句。如要設定子句,請在「Connectors」(連結器) 工作的「Task Input」(工作輸入) 區段中,按一下「filterClause」(篩選子句),然後在「Default Value」(預設值) 欄位中輸入 FilePath LIKE '/tmp/%.csv'
移動檔案 mv /tmp/dir_A/hello_world.txt /dir_B/dir_C/
  1. 在「Configure connector task」對話方塊中,按一下 Actions
  2. 選取 MoveFile 動作,然後按一下「完成」
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中,按一下 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. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中,按一下 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,請在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 部分中,按一下「entityId」 ,然後在「Default Value」(預設值) 欄位中輸入 /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. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中,按一下 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. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中,按一下 connectorInputPayload,然後在 Default Value 欄位中輸入下列內容:
    {
      "ContentBytes": "SGVsbG8gd29ybGQ=",
      "RemoteFile": "/tmp/image_1.png",
      "Overwrite": true,
      "HasBytes": true
    }
  4. 這個範例會建立 image_1.png 檔案,並將內容設為 ContentBytes 欄位中指定的值。檔案會在 SFTP 伺服器的 /tmp 目錄中建立。由於 Overwrite 屬性值為 true,因此系統會覆寫任何同名的現有檔案。

    Overwrite 屬性為選用屬性,預設值為 false

下載 ASCII 文字檔 get /tmp/myfile.txt
  1. 在「Configure connector task」對話方塊中,按一下 Actions
  2. 選取 Download 動作,然後按一下「完成」
  3. 在「Connectors」(連結器) 任務的「Task Output」(任務輸出內容) 區段中,按一下 connectorInputPayload,然後在 Default Value 欄位中輸入下列內容:
    {
    "RemoteFile": "/tmp/myfile.txt"
    }

下載檔案的內容會以字串形式,顯示在連線器工作 connectorOutputPayload 回應參數的 Content 欄位中。

下載二進位檔案 get /tmp/myfile.png
  1. 在「Configure connector task」對話方塊中,按一下 Actions
  2. 選取 Download 動作,然後按一下「完成」
  3. 在「Connectors」(連結器) 任務的「Task Output」(任務輸出內容) 區段中,按一下 connectorInputPayload,然後在 Default Value 欄位中輸入下列內容:
    {
    "RemoteFile": "/tmp/myfile.png",
    "HasBytes" : true
    }

下載檔案的內容會以 Base64 編碼字串的形式,顯示在 Connector 工作 connectorOutputPayload 回應參數的 ContentBytes 欄位中。

下載多個檔案
  1. 在「Configure connector task」對話方塊中,按一下 Actions
  2. 選取 Download 動作,然後按一下「完成」
  3. 在「Connectors」(連結器) 任務的「Task Output」(任務輸出內容) 區段中,按一下 connectorInputPayload,然後在 Default Value 欄位中輸入下列內容:
    {
    "RemoteFile": "/tmp/myfile*.txt"
    }

系統限制

SFTP 連接器每秒每節點可處理 1 筆交易,並節流任何超出此限制的交易。根據預設,Integration Connectors 會為連線分配 2 個節點 (以提高可用性)。

如要瞭解 Integration Connectors 適用的限制,請參閱「限制」一文。

使用 Terraform 建立連線

您可以使用 Terraform 資源建立新連線。

如要瞭解如何套用或移除 Terraform 設定,請參閱「基本 Terraform 指令」。

如要查看用於建立連線的 Terraform 範本範例,請參閱範本範例

使用 Terraform 建立這項連線時,您必須在 Terraform 設定檔中設定下列變數:

參數名稱 資料類型 必填 說明
remote_path STRING 安全檔案傳輸通訊協定伺服器中的目前路徑。

酬載的 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 社群尋求協助

如要發布問題及討論這個連接器,請前往 Cloud 論壇的 Google Cloud 社群。

後續步驟