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）
  サービスを有効にする方法については、サービスを有効にするをご覧ください。
以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

コネクタを構成する

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

Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。
[接続] ページに移動
[+ 新規作成] をクリックして [接続の作成] ページを開きます。
[ロケーション] セクションで、接続のロケーションを選択します。
1. リージョン: プルダウンリストからロケーションを選択します
  サポートされているすべてのリージョンの一覧については、ロケーションをご覧ください。
2. [Next] をクリックします。
[接続の詳細] セクションで、次の操作を行います。
1. コネクタ: 使用可能なコネクタのプルダウンリストから [SFTP] を選択します。
2. コネクタのバージョン: 使用可能なバージョンのプルダウンリストからコネクタのバージョンを選択します。
3. [接続名] フィールドに、接続インスタンスの名前を入力します。
  接続名は次の条件を満たす必要があります。
  - 接続名には英字、数字、ハイフンを使用できます。
  - 文字は小文字のみを使用できます。
  - 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
  - 接続名は 63 文字以内で指定してください。
4. 必要に応じて、接続インスタンスの [説明] を入力します。
5. サービスアカウント: 必要なロールを持つサービスアカウントを選択します。
6. 必要に応じて、接続ノードの設定を構成します。
  - ノードの最小数: 接続ノードの最小数を入力します。
  - ノードの最大数: 接続ノードの最大数を入力します。
  ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。
7. Remote Path: SFTP サーバーのフォルダパス。
  このフィールドは、エンティティオペレーション（List、Create、Update、Delete など）を実行する場合にのみ設定することを検討してください。
  
  ルートフォルダのエンティティ（ファイルまたはフォルダ）またはルートフォルダの直接の子フォルダにアクセスする場合は、このフィールドに値を設定する必要はありません。ただし、ルートフォルダから深さ 2 レベル以上にあるネストされたエンティティにアクセスする場合は、このフィールドの値を、アクセスするエンティティを含むフォルダのベースパスに設定する必要があります。たとえば、/folder_A/folder_B/folder_C/test.png ファイルにアクセスする場合は、リモートパスを /folder_A/folder_B/folder_C に設定する必要があります。
8. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
9. [Next] をクリックします。
[宛先] セクションに、接続するリモートホスト（バックエンドシステム）の詳細を入力します。
1. Destination Type: 宛先の種類を選択します。
  1. [ホストアドレス] フィールドに、宛先のホスト名または IP アドレスを指定します。
    1. バックエンドシステムへのプライベート接続を確立する場合は、次のようにします。
      1. PSC サービスアタッチメントを作成します。
      2. エンドポイントアタッチメントを作成し、続いて [Host address] フィールドにあるエンドポイントアタッチメントの詳細を入力します。
    2. セキュリティをさらに強化してバックエンドシステムへのパブリック接続を確立する場合は、接続用の静的送信 IP アドレスの構成を検討してから、特定の静的 IP アドレスのみを許可リストに登録するようファイアウォールルールを構成します。
  他の宛先を入力するには、[+Add destination] をクリックします。
2. [Next] をクリックします。
[認証] セクションで、認証の詳細を入力します。
1. [認証タイプ] を選択し、関連する詳細を入力します。
  SFTP 接続でサポートされる認証タイプは次のとおりです。
  - ユーザー名とパスワードを指定する
  - SSH_PUBLIC_KEY
2. [Next] をクリックします。
レビュー: 接続と認証の詳細を確認します。
[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 に適用される上限の詳細については、上限をご覧ください。

注: Integration Connectors ノードの数は、使用状況に応じて動的に自動スケーリングされます。ただし、自動スケーリングを待たずに大量の容量を確保する場合は、接続の最小ノード値を調整できます。1 つの接続により多くのトランザクションを処理するには、より多くのノードが必要です。逆に、接続が処理するトランザクションが少ない場合は、必要なノードの数が少なくなります。ノードの値を構成するには、次の手順を行います。

従量課金制をご利用のお客様は、接続の編集ページでノードの最小値と最大値を構成します。
サブスクリプションベースで利用されているお客様は、サポートにお問い合わせください。

ノードが処理できる最大トランザクションは、さまざまな要因によって異なります。そのため、スループットを高めるために最小ノードを調整する前に、バックエンドシステムが必要なトラフィックを処理するために最適に設定されているかどうかを確認することをおすすめします。

アクション

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

注: すべてのアクションの結果は、統合を実行した後に Connectors タスクの connectorOutputPayload レスポンスパラメータで JSON レスポンスとして利用できます。

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 /`	[`Configure connector task`] ダイアログで、[`Entities`] をクリックします。 `Root` エンティティを選択してから、`List` オペレーションを選択します。 [完了] をクリックします。
ディレクトリ内の `.csv` ファイルを一覧表示する	`ls /tmp/*.csv`	[`Configure connector task`] ダイアログで、[`Entities`] をクリックします。 `Entity` リストからベースディレクトリ（/tmp）を選択します。 [`List`] オペレーションを選択してから、[完了] をクリックします。フィルタ句を設定します。句を設定するには、[コネクタ] タスクの [タスク入力] セクションで [filterClause] をクリックし、[デフォルト値] に [`FilePath LIKE '/tmp/%.csv'`] を入力します。注: フィルタ句のファイルパターンの値は、単一引用符（'）で囲む必要があります。 `Entity` リストには、基本レベルのディレクトリのみが表示されます。したがって、基本レベルのディレクトリに存在するファイルのみ一覧表示できます。子ディレクトリ内のファイルの一覧表示はサポートされていません。 `FilePath` フィールドは、入力ペイロードの JSON スキーマに定義されています。使用可能なすべてのフィールドのリストについては、入力ペイロード JSON スキーマをご覧ください。インテグレーションでデータマッピングタスクを使用すると、フィルタ句を動的に設定できます。詳細については、filterClasue の動的構成をご覧ください。
ファイルの移動	`mv /tmp/dir_A/hello_world.txt /dir_B/dir_C/`	[`Configure connector task`] ダイアログで、[`Actions`] をクリックします。 [`MoveFile`] アクションを選択してから、[完了] をクリックします。 [コネクタ] タスクの [タスク入力] セクションで、`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`	[`Configure connector task`] ダイアログで、[`Actions`] をクリックします。 [`RenameFile`] アクションを選択してから、[完了] をクリックします。 [コネクタ] タスクの [タスク入力] セクションで、`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`	[`Configure connector task`] ダイアログで、[`Entities`] をクリックします。 `Entity` リストから、移動するファイルがあるベースディレクトリを選択します。 [`Delete`] オペレーションを選択してから、[完了] をクリックします。エンティティ ID をファイルのフルパスに設定します。エンティティ ID を設定するには、[コネクタ] タスクの [タスク入力] セクションで [entityId] をクリックし、[デフォルト値] に `/tmp/myfile.csv` を入力します。 [entityId] を指定する代わりに、[filterClause] を `FilePath LIKE '/tmp/myfile.csv'` に設定することもできます。
ASCII テキストファイルのアップロード	`put file_1.txt /tmp/file_1.txt`	[`Configure connector task`] ダイアログで、[`Actions`] をクリックします。 [`Upload`] アクションを選択してから、[完了] をクリックします。 [コネクタ] タスクの [タスク入力] セクションで、`connectorInputPayload` をクリックし、`Default Value`フィールドに次のように入力します。 { "Content": "This is a sample text!\r\n", "RemoteFile": "/tmp/file_1.txt", "Overwrite": true } このサンプルでは、SFTP サーバーの `/tmp` ディレクトリに `This is a sample text!` というコンテンツがある `file_1.txt` ファイルを作成します。また、`Overwrite` 属性値が `true` のため、同じ名前の既存のファイルはすべて上書きされます。 `Overwrite` 属性の設定は省略可能です。デフォルト値は `false` です。注: ローカルファイルを SFTP サーバーに直接アップロードすることはできません。`Content` 属性には、ファイルの内容全体を指定する必要があります。
バイナリファイルのアップロード	`put image_1.png /tmp/image_1.png`	バイナリコンテンツをアップロードするには、まずコンテンツを Base64 形式でエンコードする必要があります。任意のツールを選択して、コンテンツをエンコードします。コンテンツをエンコードする手順は、このドキュメントの範囲外です。コンテンツを Base64 文字列として取得したら、次の手順を行います。 [`Configure connector task`] ダイアログで、[`Actions`] をクリックします。 [`Upload`] アクションを選択してから、[完了] をクリックします。 [コネクタ] タスクの [タスク入力] セクションで、`connectorInputPayload` をクリックし、`Default Value`フィールドに次のように入力します。 { "ContentBytes": "SGVsbG8gd29ybGQ=", "RemoteFile": "/tmp/image_1.png", "Overwrite": true, "HasBytes": true } このサンプルでは、`ContentBytes` フィールドで指定されたコンテンツを含む `image_1.png` ファイルを作成します。ファイルは、SFTP サーバーの `/tmp` ディレクトリに作成されます。また、`Overwrite` 属性値が `true` のため、同じ名前の既存のファイルはすべて上書きされます。 `Overwrite` 属性の設定は省略可能です。デフォルト値は `false` です。
ASCII テキストファイルをダウンロードする	`get /tmp/myfile.txt`	[`Configure connector task`] ダイアログで、[`Actions`] をクリックします。 [`Download`] アクションを選択してから、[完了] をクリックします。 [コネクタ] タスクの [タスク出力] セクションで、`connectorInputPayload` をクリックし、`Default Value`フィールドに次のように入力します。 { "RemoteFile": "/tmp/myfile.txt" } ダウンロードしたファイルのコンテンツは、Connectors タスクの `connectorOutputPayload` レスポンスパラメータの `Content` フィールドで文字列として利用できます。
バイナリファイルをダウンロードする	`get /tmp/myfile.png`	[`Configure connector task`] ダイアログで、[`Actions`] をクリックします。 [`Download`] アクションを選択してから、[完了] をクリックします。 [コネクタ] タスクの [タスク出力] セクションで、`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 フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。