SFTP

SFTP コネクタを使用すると、SFTP サーバーに接続してファイル転送オペレーションを実行できます。

始める前に

SFTP コネクタを使用する前に、次の作業を行います。

  • Google Cloud プロジェクトで次の操作を行います。
    • コネクタを構成するユーザーに roles/connectors.admin IAM ロールを付与します。
    • コネクタに使用するサービス アカウントに、次の IAM ロールを付与します。
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      サービス アカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスするのに認証を受ける必要がある人間以外のユーザーを表します。サービス アカウントがない場合は、サービス アカウントを作成する必要があります。詳細については、サービス アカウントを作成するをご覧ください。

    • 次のサービスを有効にします。
      • secretmanager.googleapis.com(Secret Manager API)
      • connectors.googleapis.com(Connectors API)

      サービスを有効にする方法については、サービスを有効にするをご覧ください。

    以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

コネクタを構成する

コネクタを構成するには、データソース(バックエンド システム)への接続を作成する必要があります。接続はデータソースに特有です。つまり、多数のデータソースがある場合は、データソースごとに別々の接続を作成する必要があります。接続を作成する手順は次のとおりです。

  1. Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。

    [接続] ページに移動

  2. [+ 新規作成] をクリックして [接続の作成] ページを開きます。
  3. [ロケーション] セクションで、接続のロケーションを選択します。
    1. リージョン: プルダウン リストからロケーションを選択します

      サポートされているすべてのリージョンの一覧については、ロケーションをご覧ください。

    2. [Next] をクリックします。
  4. [接続の詳細] セクションで、次の操作を行います。
    1. コネクタ: 使用可能なコネクタのプルダウン リストから [SFTP] を選択します。
    2. コネクタのバージョン: 使用可能なバージョンのプルダウン リストからコネクタのバージョンを選択します。
    3. [接続名] フィールドに、接続インスタンスの名前を入力します。

      接続名は次の条件を満たす必要があります。

      • 接続名には英字、数字、ハイフンを使用できます。
      • 文字は小文字のみを使用できます。
      • 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
      • 接続名は 63 文字以内で指定してください。
    4. 必要に応じて、接続インスタンスの [説明] を入力します。
    5. サービス アカウント: 必要なロールを持つサービス アカウントを選択します。
    6. 必要に応じて、接続ノードの設定を構成します。

      • ノードの最小数: 接続ノードの最小数を入力します。
      • ノードの最大数: 接続ノードの最大数を入力します。

      ノードは、トランザクションを処理する接続の単位(またはレプリカ)です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され(可用性を高めるため)、最大ノード数は 50 に設定されます。

    7. Remote Path: SFTP サーバーのフォルダパス。

      このフィールドは、エンティティ オペレーション(ListCreateUpdateDelete など)を実行する場合にのみ設定することを検討してください。

      ルートフォルダのエンティティ(ファイルまたはフォルダ)またはルートフォルダの直接の子フォルダにアクセスする場合は、このフィールドに値を設定する必要はありません。ただし、ルートフォルダから深さ 2 レベル以上にあるネストされたエンティティにアクセスする場合は、このフィールドの値を、アクセスするエンティティを含むフォルダのベースパスに設定する必要があります。たとえば、/folder_A/folder_B/folder_C/test.png ファイルにアクセスする場合は、リモートパスを /folder_A/folder_B/folder_C に設定する必要があります。

    8. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
    9. [Next] をクリックします。
  5. [宛先] セクションに、接続するリモートホスト(バックエンド システム)の詳細を入力します。
    1. Destination Type: 宛先の種類を選択します。
      1. [ホストアドレス] フィールドに、宛先のホスト名または IP アドレスを指定します。
        1. バックエンド システムへのプライベート接続を確立する場合は、次のようにします。
          1. PSC サービス アタッチメントを作成します。
          2. エンドポイント アタッチメントを作成し、続いて [Host address] フィールドにあるエンドポイント アタッチメントの詳細を入力します。
        2. セキュリティをさらに強化してバックエンド システムへのパブリック接続を確立する場合は、接続用の静的送信 IP アドレスの構成を検討してから、特定の静的 IP アドレスのみを許可リストに登録するようファイアウォール ルールを構成します。

      他の宛先を入力するには、[+Add destination] をクリックします。

    2. [Next] をクリックします。
  6. [認証] セクションで、認証の詳細を入力します。
    1. [認証タイプ] を選択し、関連する詳細を入力します。

      SFTP 接続でサポートされる認証タイプは次のとおりです。

      • ユーザー名とパスワードを指定する
      • SSH_PUBLIC_KEY
    2. これらの認証タイプの構成方法については、認証を構成するをご覧ください。

    3. [Next] をクリックします。
  7. レビュー: 接続と認証の詳細を確認します。
  8. [Create(作成)] をクリックします。

認証を構成する

使用する認証に基づいて詳細を入力します。

  • ユーザー名とパスワード
    • ユーザー名: 接続に使用する SFTP ユーザー名。
    • パスワード: SFTP ユーザー名に関連付けられたパスワードを含む Secret Manager の Secret。
  • SSH_PUBLIC_KEY
    • ユーザー名: 認証に使用される SFTP ユーザー アカウント。
    • SSH Private Key: SSH 認証用の秘密鍵。
    • SSH 秘密鍵パスワード: 秘密鍵を保護するパスフレーズまたはパスワード(ある場合)。
    • SSH 秘密鍵タイプ: 秘密鍵の形式。

エンティティ、オペレーション、アクション

すべての Integration Connectors が、接続されたアプリケーションのオブジェクトを抽象化するレイヤを提供します。アプリケーションのオブジェクトには、この抽象化を通じてのみアクセスできます。抽象化は、エンティティ、オペレーション、アクションとして公開されます。

  • エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベース コネクタでは、テーブルがエンティティであり、ファイル サーバー コネクタでは、フォルダがエンティティです。また、メッセージング システム コネクタでは、キューがエンティティです。

    ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。

  • オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。

    使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティ オペレーションをご覧ください。ただし、コネクタがどのエンティティ オペレーションもサポートしていない場合、サポートされていないオペレーションは Operations リストに表示されません。

  • アクション: コネクタ インターフェースを介して統合で使用できる最初のクラス関数です。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

システムの上限

SFTP コネクタは、ノードごとに 1 秒あたり 1 件のトランザクションを処理することができ、この上限を超えるトランザクションはすべてスロットルされます。デフォルトでは、Integration Connectors は、接続に 2 つのノードを割り当てます(可用性を高めるため)。

Integration Connectors に適用される上限の詳細については、上限をご覧ください。

アクション

このセクションでは、コネクタでサポートされているアクションを一覧表示します。アクションの構成方法については、アクションの例をご覧ください。

Upload アクション

次の表では、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 を入力します。

    [entityId] を指定する代わりに、[filterClause] を FilePath LIKE '/tmp/myfile.csv' に設定することもできます。

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. このサンプルでは、SFTP サーバーの /tmp ディレクトリに This is a sample text! というコンテンツがある file_1.txt ファイルを作成します。また、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"
    }

ダウンロードしたファイルのコンテンツは、Connectors タスクの connectorOutputPayload レスポンス パラメータの Content フィールドで文字列として利用できます。

バイナリ ファイルをダウンロードする get /tmp/myfile.png
  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [Download] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク出力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のように入力します。
    
    {
    "RemoteFile": "/tmp/myfile.png",
    "HasBytes" : true
    }

ダウンロードしたファイルのコンテンツは、Connectors タスクの connectorOutputPayload レスポンス パラメータの ContentBytes フィールドで Base64 エンコード文字列として利用できます。

ペイロード用の 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
      }
    }
  }

filterClause の動的構成

リスト、更新、削除のオペレーションでは、統合のデータ マッピングタスクを使用して、実行時に filterClasue 入力変数の値を動的に設定できます。たとえば、統合の API トリガーを呼び出すときに、フィルタ句の値を送信できます。次の画像は、データ マッピング タスクのデータ マッピング エディタの filterClause 変数のサンプル マッピングを示しています。 データ マッピング エディタでフィルタ句を設定する

Terraform を使用して接続を作成する

Terraform リソースを使用して、新しい接続を作成できます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

接続作成用の Terraform テンプレートのサンプルを表示するには、サンプル テンプレートをご覧ください。

Terraform を使用してこの接続を作成する場合は、Terraform 構成ファイルで次の変数を設定する必要があります。

パラメータ名 データ型 必須 説明
remote_path STRING False SFTP サーバーの現在のパス。

インテグレーションで SFTP 接続を使用する

接続を作成すると、Apigee Integration と Application Integration の両方で使用できるようになります。この接続は、コネクタタスクを介して統合で使用できます。

  • Apigee Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。
  • Application Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。

Google Cloud コミュニティの助けを借りる

Google Cloud コミュニティの Cloud フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。

次のステップ