Amazon S3

Amazon S3 コネクタを使用すると、Amazon S3 のバケットとオブジェクトへの SQL アクセスが可能になります。

準備

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

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. コネクタ: 使用可能なコネクタのプルダウンリストから [Amazon S3] を選択します。
2. コネクタのバージョン: 使用可能なバージョンのプルダウンリストからコネクタのバージョンを選択します。
3. [接続名] フィールドに、接続インスタンスの名前を入力します。
  接続名は次の条件を満たす必要があります。
  - 接続名には英字、数字、ハイフンを使用できます。
  - 文字は小文字のみを使用できます。
  - 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
  - 接続名は 63 文字以内で指定してください。
4. 必要に応じて、接続インスタンスの [説明] を入力します。
5. サービスアカウント: 必要なロールを持つサービスアカウントを選択します。
6. 必要に応じて、接続ノードの設定を構成します。
  - ノードの最小数: 接続ノードの最小数を入力します。
  - ノードの最大数: 接続ノードの最大数を入力します。
  ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。
7. AWS リージョン: Amazon S3 インスタンスがホストされているリージョン
8. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
9. [Next] をクリックします。
[宛先] セクションに、接続するリモートホスト（バックエンドシステム）の詳細を入力します。
1. Destination Type: 宛先の種類を選択します。
  1. [ホストアドレス] フィールドに、宛先のホスト名または IP アドレスを指定します。
    1. バックエンドシステムへのプライベート接続を確立する場合は、次のようにします。
      1. PSC サービスアタッチメントを作成します。
      2. エンドポイントアタッチメントを作成し、続いて [Host address] フィールドにあるエンドポイントアタッチメントの詳細を入力します。
    2. セキュリティをさらに強化してバックエンドシステムへのパブリック接続を確立する場合は、接続用の静的送信 IP アドレスの構成を検討してから、特定の静的 IP アドレスのみを許可リストに登録するようファイアウォールルールを構成します。
  他の宛先を入力するには、[+Add destination] をクリックします。
2. [Next] をクリックします。
[認証] セクションで、認証の詳細を入力します。
1. [認証タイプ] を選択し、関連する詳細を入力します。
  Amazon S3 接続では、次の認証タイプがサポートされています。
  - ルート認証情報
  - AWS IAM ロール
  - AWS の一時的な認証情報
2. [Next] をクリックします。
レビュー: 接続と認証の詳細を確認します。
[Create（作成）] をクリックします。

認証を構成する

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

ルート認証情報
アカウントのルート認証情報を使用して認証するには。
- AWS アクセスキー: root ユーザーのアクセスキー
- AWS アクセスシークレット: root ユーザーの秘密鍵

AWS IAM ロール
AWS IAM ロールを使用して認証するには。
- AWS アクセスキー: ロールを想定する IAM ユーザーのアクセスキー
- AWS アクセスシークレット: ロールを想定する IAM ユーザーの秘密鍵。
- AWS ロールの ARN: 認証するロールのロール ARN を指定します。指定したロールの認証情報のみが取得されます。
- AWS 外部 ID: 別のアカウントでロールを想定している場合にのみ必要です。

AWS の一時的な認証情報
一時的な認証情報を使用して認証するには
- AWS アクセスキー: ロールを想定する IAM ユーザーのアクセスキー
- AWS アクセスシークレット: ロールを想定する IAM ユーザーの秘密鍵。
- AWS セッショントークン: 一時的な認証情報とは別に生成されます。
- AWS ロールの ARN: 認証するロールのロール ARN を指定します。指定したロールの認証情報のみが取得されます。
- AWS 外部 ID: 別のアカウントでロールを想定している場合にのみ必要です。

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

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

エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベースコネクタでは、テーブルがエンティティであり、ファイルサーバーコネクタでは、フォルダがエンティティです。また、メッセージングシステムコネクタでは、キューがエンティティです。
ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。
オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。
- リスト
- 取得
- 作成
- 更新
- 削除
使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティオペレーションをご覧ください。ただし、コネクタがどのエンティティオペレーションもサポートしていない場合、サポートされていないオペレーションは Operations リストに表示されません。
アクション: コネクタインターフェースを介して統合で使用できる最初のクラス関数です。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

アクション

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

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

CopyObject アクション

このアクションにより、あるバケットから別のバケットにオブジェクトをコピーしたり、同じバケット内にオブジェクトをコピーしたりできます。

CopyObject アクションの入力パラメータ

パラメーター名	データ型	必須	説明
BucketSource	文字列	○	オブジェクトのコピー元とする必要があるバケット名。
ObjectSource	オブジェクト	○	コピーする必要があるオブジェクトの名前。
BucketDestination	文字列	○	オブジェクトのコピー先とする必要があるバケット名。
ObjectDestination	文字列	いいえ	転送先バケット内のオブジェクトの名前。指定しない場合、名前は元の名前と同じになります。

CopyObject アクションの出力パラメータ

このアクションは、コピーが正常に完了した場合、ステータス 200（OK）を返します。

CopyObject アクションの構成方法については、アクションの例をご覧ください。

DownloadObject アクション

このアクションにより、バケットから 1 つ以上のオブジェクトを取得します。

DownloadObjects アクションの入力パラメータ

パラメーター名	データ型	必須	説明
バケット	文字列	○	ダウンロードするオブジェクトが格納されているバケット名。
オブジェクト	文字列	いいえ	ダウンロードする必要があるオブジェクトの名前。指定しない場合は、指定したバケットからすべてのオブジェクトがダウンロードされます。
HasBytes	ブール値	○	コンテンツを Base64 エンコード文字列としてダウンロードするかどうかを指定します。
UpdatedStartDate	日時	いいえ	オブジェクトをダウンロードする期間の開始日。指定しない場合、最も古い日付から UpdateEndDate までのオブジェクトがダウンロードされます。
UpdatedEndDate	日時	いいえ	オブジェクトをダウンロードする期間の終了日。指定しない場合、指定された UpdateStartDate から現在の日付までオブジェクトがダウンロードされます。

DownloadObjects アクションの出力パラメータ

このアクションは、ダウンロードが正常に完了した場合、ステータス 200（OK）を返します。

DownloadObjects アクションの構成方法については、アクションの例をご覧ください。

UploadObject アクション

このアクションにより、オブジェクトをバケットにアップロードできます。

UploadObject アクションの入力パラメータ

パラメーター名	データ型	必須	説明
バケット	文字列	○	オブジェクトをアップロードするバケット名。
ContentBytes	文字列	いいえ	ファイルとしてアップロードするバイトコンテンツ。
HasBytes	ブール値	○	コンテンツを Base64 エンコード文字列としてアップロードする必要があるかどうかを指定します。
AccessPolicy	文字列	いいえ	このオブジェクトのアクセスポリシーです。使用できる値は、PRIVATE、ANONREAD、ANONREADWRITE、AUTHREAD です。デフォルト値は PRIVATE です。
コンテンツ	文字列	いいえ	アップロードするコンテンツ。
FileName	文字列	いいえ	アップロードするファイルの名前。FileContent パラメータを指定する場合、この値は必須です。

UploadObject アクションの出力パラメータ

このアクションは、オブジェクトのアップロードが正常に完了した場合、ステータス 200（OK）を返します。

UploadObject アクションの構成方法については、アクションの例をご覧ください。

DeleteObject アクション

このアクションにより、バケットからオブジェクトを削除できます。

DeleteObject アクションの入力パラメータ

パラメーター名	データ型	必須	説明
バケット	文字列	○	削除するオブジェクトが格納されているバケット名。
オブジェクト	文字列	○	削除する必要があるオブジェクトの名前。

DeleteObject アクションの出力パラメータ

このアクションは、削除が正常に完了した場合、ステータス 200（OK）を返します。

DeleteObject アクションの構成方法については、アクションの例をご覧ください。

MoveObject アクション

このアクションにより、ユーザーは特定のバケットの既存のオブジェクトを別のバケットへ、または同じバケット内で移動できます。

MoveObject アクションの入力パラメータ

パラメーター名	データ型	必須	説明
BucketSource	文字列	○	移動するオブジェクトが存在しているソースバケット名。
ObjectSource	文字列	○	移動する必要があるオブジェクトの名前。
BucketDestination	文字列	○	オブジェクトの移動先とする必要がある宛先バケット名。
ObjectDestination	文字列	いいえ	転送先バケット内のオブジェクトの名前。指定しない場合、元の名前が保持されます。

MoveObject アクションの出力パラメータ

このアクションは、移動オペレーションが正常に完了した場合、ステータス 200（OK）を返します。

MoveObject アクションの構成方法については、アクションの例をご覧ください。

PutBucketAcl アクション

このアクションにより、バケットのアクセス制御リスト（ACL）を更新できます。

PutBucketAcl アクションの入力パラメータ

パラメーター名	データ型	必須	説明
バケット	文字列	○	ACL を適用する必要があるバケット名。
ACL	文字列	○	バケットに適用されるアクセスレベル。

PutBucketAcl アクションの出力パラメータ

このアクションは、バケット ACL の更新が正常に完了した場合、ステータス 200（OK）を返します。

PutBucketAcl アクションの構成方法については、アクションの例をご覧ください。

PutObjectAcl アクション

このアクションにより、バケット内のオブジェクトのアクセス制御リスト（ACL）を更新できます。

PutObjectAcl アクションの入力パラメータ

パラメーター名	データ型	必須	説明
バケット	文字列	○	オブジェクトが存在するバケット名。
ACL	文字列	○	オブジェクトに適用されるアクセスレベル。
凡例	文字列	○	ACL を適用する必要があるオブジェクト名。

PutObjectAcl アクションの出力パラメータ

このアクションは、オブジェクト ACL の更新が正常に完了した場合、ステータス 200（OK）を返します。

PutObjectAcl アクションの構成方法については、アクションの例をご覧ください。

アクションの例

このセクションでは、このコネクタでいくつかのアクションを実行する方法について説明します。

例 - オブジェクトをコピーする

この例では、オブジェクトを 1 つのバケットから別のバケットにコピーします。

[Configure connector task] ダイアログで、[Actions] をクリックします。
[CopyObject] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"BucketSource": "aws-s3-bucket-source",
"ObjectSource": "pic.jpg",
"BucketDestination": "aws-s3-bucket-destination",
"ObjectDestination": "new_pic.jpg"
}
```

アクションが成功すると、CopyObject タスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Status": "Success"
}]

例 - オブジェクトをダウンロードする

この例では、指定したバケットからオブジェクトをダウンロードします。

[Configure connector task] ダイアログで、[Actions] をクリックします。
[DownloadObjects] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"Bucket": "aws-s3-bucket-source",
"HasBytes": true
}
```

アクションが成功すると、DownloadObjects タスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Success": "True",
"RemoteFile": "prefix1%2Faws-s3-bucket-source%2Finventory-test-1%2F2023-09-10T01-00Z%2Fmanifest.json",
"ContentBytes": "ewogICJzb3VyY2VCdWNrZXQiIDogImF3cy1zMy1idWNrZXQtYmNvbmUiLAogICJnOK"
},
{
"Success": "True",
"RemoteFile": "upload1.txt",
"ContentBytes": "VGhpcyBpcyBhIHRlc3RpbmcgZmlsZQ=="
}]

例 - オブジェクトをアップロードする

この例では、指定したバケットにオブジェクトをアップロードします。

[Configure connector task] ダイアログで、[Actions] をクリックします。
[UploadObject] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"Bucket": "aws-s3-bucket-source",
"FileName": "upload_1.txt",
"Content": "This is a testing file",
"AccessPolicy": "PUBLIC"
}
```

アクションが成功すると、UploadObject タスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Status": "success",
"bucket": "aws-s3-bucket-source",
"rss:title": "Object 'upload_1.txt' was created in the bucket: aws-s3-bucket-source",
"object": "upload_1.txt"
}]

例 - オブジェクトを削除する

この例では、指定したバケットからオブジェクトを削除します。

[Configure connector task] ダイアログで、[Actions] をクリックします。
[DeleteObject] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"Bucket": "aws-s3-bucket-source",
"Object": "abc.png"
}
```

アクションが成功すると、DeleteObject タスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Status": "Success"
}]

例 - オブジェクトを移動する

この例では、オブジェクトを 1 つのバケットから別のバケットに移動します。

[Configure connector task] ダイアログで、[Actions] をクリックします。
[MoveObject] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"BucketSource": "aws-s3-bucket-source",
"ObjectSource": "abc.png",
"BucketDestination": "aws-s3-bucket-destination",
"ObjectDestination": "moved.png"
}
```

アクションが成功すると、MoveObject タスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Status": "Success"
}]

例 - バケットの ACL を更新する

この例では、バケットのアクセス制御権限を更新します。

[Configure connector task] ダイアログで、[Actions] をクリックします。
[PutBucketAcl] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"BucketSource": "aws-s3-bucket-source",
"ACL": "public-read"
}
```

アクションが成功すると、PutBucketAcl タスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Status": "Success"
}]

例 - オブジェクトの ACL を更新する

この例では、バケット内のオブジェクトのアクセス制御権限を更新します。

[Configure connector task] ダイアログで、[Actions] をクリックします。
[PutObjectAcl] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"Bucket": "aws-s3-bucket-source",
"ACL": "aws-exec-read",
"Key": "AWS_S3_BusinessCase_V2.xlsx"
}
```

アクションが成功すると、PutObjectAcl タスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Status": "Success"
}]

エンティティオペレーションの例

このセクションでは、このコネクタでエンティティオペレーションの一部を実行する方法について説明します。

例 - すべてのオブジェクトのメタデータを一覧表示する

この例では、Object エンティティに含まれるすべてのオブジェクトのメタデータをフェッチします。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Object を選択します。
[List] オペレーションを選択してから、[完了] をクリックします。
必要に応じて、コネクタタスクの [タスク入力] セクションでフィルタ句を指定して、結果セットをフィルタリングできます。フィルタ句の値は常に単一引用符（'）内で指定します。例: Bucket='test-bucket'。また、論理演算子を使用して複数のフィルタ条件を指定することもできます。例: Bucket='test-bucket' and OwnerId='b1ecc809ad8467088afb'。

例 - バケットのメタデータを取得する

この例では、指定された ID を持つバケットのメタデータを Bucket エンティティから取得します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Bucket を選択します。
[Get] オペレーションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで [EntityId] をクリックし、[デフォルト値] フィールドに demo_replication を入力します。
ここで、demo_replication は Bucket エンティティ内の一意のバケット ID です。

例 - バケットを作成する

この例では、Bucket エンティティにバケットを作成します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Bucket を選択します。
[Create] オペレーションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"Bucket": "Demo1697528098686",
"OwnerId": "b1ecc809ad8467088afb6beed9581815e4f203f70d19553de2e5d23623ac6647",
"OwnerDisplayName": "awsr_adm.cpp"
}
```
統合に成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。
```
[{
"Bucket": "Demo1697528098686"
}]
```

例 - バケットを削除する

この例では、Bucket エンティティ内の指定された ID のバケットを削除します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Bucket を選択します。
[Delete] オペレーションを選択してから、[完了] をクリックします。
[コネクタタスクの [タスク入力 セクションで [entityId] をクリックし、[デフォルト値] フィールドに demo1697528098686 を入力します。

統合で Amazon S3 接続を使用する

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

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

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

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