Foundry データセット向けの S3 対応 API

Foundry データセット向けの S3 対応 API を使用すると、Foundry データセットを S3 バケットのように操作できます。API 経由でアクセスしたときのデータセットの動作を確認し、セットアップガイドと例を参照してください。

Foundry は Amazon Simple Storage Service (S3) API ↗ の一部を公開しており、S3 ストレージサービスと通信できるクライアントを使用して Foundry データセットを操作できます。たとえば、AWS CLI、AWS SDK、Hadoop S3 ファイルシステム、Cyberduck などがあります。

S3 の概念すべてが Foundry の概念に自然に対応するわけではないため、S3 API は完全には実装されていません。たとえば、バケット（Foundry データセットに相当）の作成と削除には現在対応していません。API を使用する前に、Foundry でデータセットを作成してください。ただし、マルチパートアップロードを含む、ファイルの読み取り、書き込み、削除のワークフローの大半に対応しています。対応している S3 アクションの一覧については、対応しているアクションを参照してください。

概念

このセクションでは、S3 の概念と Foundry データセットの概念の対応関係を説明します。

S3 バケットと Foundry データセットの対応

S3 バケットは Foundry データセットに対応し、バケット名は Foundry データセットの一意の識別子（たとえば、ri.foundry.main.dataset.bafb7e96-84f1-4d23-a4a5-40b17c6912e7）になります。

S3 オブジェクトキーは、Foundry データセット内のファイルの論理パス（たとえば、top-level-file.csv や subfolder/nested-file.csv）に対応します。

ブランチ

この API は、英数字（a-z、A-Z、0-9 のみ）または特殊文字 - と _ を含む名前のデータセットブランチへのアクセスに対応しています。ブランチを指定するには、バケット名にピリオドで区切ってブランチ名を追加し、<dataset-rid>.<branch-name> のように変更します。ブランチを指定しない場合は、デフォルトのブランチが使用されます。

たとえば、RID が ri.foundry.main.dataset.bafb7e96-84f1-4d23-a4a5-40b17c6912e7 のデータセットの mybranch ブランチにアクセスするには、バケット名 ri.foundry.main.dataset.bafb7e96-84f1-4d23-a4a5-40b17c6912e7.mybranch を使用します。

S3 バケット名の検証には、前述の文字制限が適用されます。ブランチ名に / などの許可されていない文字が含まれる場合は、Base64 エンコードを使用してブランチ名をエンコードできます。末尾の = 文字は省略してください。たとえば、feature/my-branch を Base64 エンコードすると ZmVhdHVyZS9teS1icmFuY2g= になります。バケット名でこのブランチを参照するには、ZmVhdHVyZS9teS1icmFuY2g（= 文字を除いたもの）を使用できます。

この API はブランチの作成に対応していません。指定するブランチは、データセットにすでに存在している必要があります。

トランザクション

この API は、ブランチと同様の方法でデータセットのトランザクションにアクセスすることに対応しています。これにより、ユーザーはデータセットの過去のバージョンにアクセスできます。たとえば、RID が ri.foundry.main.dataset.bafb7e96-84f1-4d23-a4a5-40b17c6912e7 のデータセットの ri.foundry.main.transaction.0cdfe8c9-f595-4859-a194-7daecff9d6fe トランザクションにアクセスするには、バケット名 ri.foundry.main.dataset.bafb7e96-84f1-4d23-a4a5-40b17c6912e7.ri.foundry.main.transaction.0cdfe8c9-f595-4859-a194-7daecff9d6fe を使用します。

この方法でアクセスできるのは、コミット済みのトランザクションのみです。そのため、バケットは読み取り専用になります。トランザクション識別子を含むバケット名を使用する場合、オブジェクトの書き込みや削除はできません。

トランザクション管理

S3 にはトランザクションの概念がないため、Foundry データセットのトランザクションは、次の動作に従って自動的に処理されます。

1. トランザクションは、ユーザーがファイルを書き込むか削除するときに、必要に応じて開かれます。
2. この API は、複数のファイルの同時書き込み_または_複数のファイルの同時削除に対応しています。ファイルは同じ未コミットのトランザクション内で変更され、書き込みには UPDATE トランザクション、削除には DELETE トランザクションが使用されます。
3. この API は、書き込み_と_削除の同時実行には対応していません。同時実行には、UPDATE トランザクションと DELETE トランザクションの両方が同時にアクティブである必要があるためです。これは、ブランチに存在できる未コミットのトランザクションは最大1個であるという、プラットフォーム全体の保証によるものです。書き込みまたは削除のリクエストのうち、先にプラットフォームに到達したものが、対応するトランザクションを開きます。もう一方の種類のリクエストは、最初のトランザクションがコミットされるまで（後述の自動コミット動作に従って）、自身のトランザクションを開くことができません。これによって、データセットが不整合な状態になるリスクはありません。書き込みと削除が同時に適用されたり、交互に混在して適用されたりすることはなく、タイミングに左右されるのは、この2種類のリクエストが処理される順序のみです。
4. トランザクションは、書き込みまたは削除の後、操作がない状態が短時間続くと自動的にコミットされます。これにより、同じトランザクションで複数のファイルをアップロードでき、ファイル数がごく少ないトランザクションが多数発生することを回避できます。たとえば、ファイルが継続的にアップロードされ、操作がない期間が生じない場合などに、トランザクションが無期限に開いたままになることを防ぐため、一定時間が経過すると、実行中のアップロードがなくなり次第、トランザクションがコミットされます。ファイルが継続的に並列アップロードされる場合は、すべてのアップロードが完了するまでトランザクションは開いたままになります。
5. トランザクションが開いており、操作がない期間中に読み取りリクエストを受信した場合、可能であれば UPDATE トランザクションと DELETE トランザクションは即座にコミットされます。これは、S3 で一般的に期待される書き込み後の読み取りのセマンティクスを維持することを目的としています。ただし、開いているトランザクションへの書き込みリクエストがまだ実行中に読み取りが試みられた場合、読み取りは最新のコミット済みのビューから行われます。すべての書き込みまたは削除の完了後にトランザクションがコミットされることを保証するには、新しい書き込みまたは削除のリクエストを送る前に、続けて読み取りリクエストを送信できます。

上記の動作により、書き込み後の読み取りのセマンティクスは保証されません。ただし、可能な場合にはこれを実現できるよう、最大限の対応が行われます。

認証

API 経由の接続は、アクセスキーIDとシークレットアクセスキーの資格情報を使用して認証されます。

固定の資格情報

固定の資格情報は、標準の AWS アクセスキーIDとシークレットアクセスキーの資格情報に似ています。固定の資格情報は有効期間が長く、Foundry では、Foundry の Control Panel に登録されたサードパーティアプリケーションのサービスユーザーに関連付けられます。

固定のアクセスキーIDとシークレットアクセスキーを使用して S3 互換 API 経由でデータセットに接続する場合、アクセスレベルはサードパーティアプリケーションのサービスユーザーに付与されたアクセス権によって決まります。固定の資格情報は、個別のプロジェクトに制限する必要があります。プロジェクトの制限は、新しい資格情報を生成するときに指定します。生成された資格情報を使用してアクセスできるのは、指定したプロジェクト内のデータセットのみです。

/io/s3/api/v2/credentials API エンドポイントを使用してこれらの資格情報を生成する方法については、以下のセットアップガイドを参照してください。

一時的な資格情報

有効期間の長い資格情報が必要なワークフローや、アクセスをサービスユーザーに関連付けることが有益なワークフローでは、固定の資格情報の使用を推奨します。通常の Foundry ユーザーとして API に対して認証する場合は、ユーザー認証トークンを一時的な S3 資格情報と交換できます。このトークンは、サードパーティアプリケーション向けの OAuth2 のいずれかのグラントを通じて取得することもできます。

一時的な資格情報は、標準の AssumeRoleWithWebIdentity ↗ Security Token Service (STS) API を使用して取得します。必要なのは、WebIdentityToken リクエストパラメーターが存在し、上記の通常の Foundry トークンが設定されていることだけです。返される一時的な資格情報のスコープは、指定したトークンのスコープと同一です。DurationSeconds パラメーターを指定して、資格情報の有効期間を設定できます。資格情報の有効期間は最大1時間で、一時的な資格情報の取得に使用した Foundry トークンの有効期間を超えることはありません。

STS API には https://<FOUNDRY_URL>/io/s3 でアクセスできます。プログラムで STS 資格情報を取得する場合は、標準の STS クライアントまたは資格情報プロバイダーのエンドポイント設定にこの URL を設定してください。例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
import boto3

endpoint = "https://<FOUNDRY_URL>/io/s3"

session = boto3.session.Session()
client = session.client(service_name='sts', endpoint_url=endpoint)

# RoleArn と RoleSessionName は使用されませんが、boto3 では必須のパラメーターです
credentials = client.assume_role_with_web_identity(
    RoleArn="xxxxxxxxxxxxxxxxxxxx",
    RoleSessionName="xxxxx",
    WebIdentityToken=token
)["Credentials"]

または、以下の例のように、cURL または同等のツールを使用して API に直接アクセスできます。<TOKEN> は有効な Foundry トークンに置き換えてください。

Copied!
1
2
curl -X POST \
    "https://<FOUNDRY_URL>/io/s3?Action=AssumeRoleWithWebIdentity&WebIdentityToken=<TOKEN>"

以下に示すように、XML レスポンスでセッション資格情報を受け取ります。これらの資格情報は安全に保管してください。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
<?xml version='1.0' encoding='UTF-8'?>
<AssumeRoleWithWebIdentityResponse
	xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
	<AssumeRoleWithWebIdentityResult>
		<Credentials>
			<AccessKeyId>PLTRLZZJE0...</AccessKeyId>
			<SecretAccessKey>2j3hKX4EDP...</SecretAccessKey>
			<SessionToken>eyJwbG50ci...</SessionToken>
			<Expiration>2023-08-30T10:55:08.841403951Z</Expiration>
		</Credentials>
	</AssumeRoleWithWebIdentityResult>
</AssumeRoleWithWebIdentityResponse>

一時的な資格情報を取得したら、以下のセットアップガイドのステップ4に進み、S3 クライアントの設定方法を確認します。サードパーティアプリケーションに関する手順に従う必要はありません。S3 クライアントを設定するときは、セッショントークン、アクセスキーID、シークレットアクセスキーを指定する必要があります。

パス形式アクセスの URL

API は、パス形式アクセス ↗によるバケットへのアクセスのみに対応しています。バケット URL は https://<FOUNDRY_URL>/io/s3/<bucket-name>/<key-name> という形式になります。

Foundry の用語に置き換えると、これは https://<FOUNDRY_URL>/io/s3/<dataset-rid>/<logical-filepath> になります。

仮想ホスト形式のバケットアクセス（URL のサブドメインにバケット名が含まれる形式）には、現在対応していません。

署名付き URL

putObject 操作では署名付き URL を使用できます。

セットアップガイド

S3 クライアントから API への接続を設定するには、次の手順に沿って進めてください。

1. Foundry でサードパーティアプリケーションを登録する
2. サードパーティアプリケーションのサービスユーザーに権限を付与する
3. S3 アクセスキーIDとシークレットアクセスキーを生成する
4. S3 クライアントを設定する

特定の S3 クライアントの設定例を表示する。

ステップ1：Foundry でサードパーティアプリケーションを登録する

S3 互換 API の資格情報を取得するには、まず Foundry の Control Panel で作成されたサードパーティアプリケーションのクライアントIDとシークレットを取得する必要があります。プロジェクト制限の要件と動作、および生成される資格情報のスコープについては、認証の概念を確認してください。アプリケーションを登録するには、次の手順を実行します。

1. Foundry で Control Panel を開きます。
2. サイドバーでサードパーティーのアプリケーション（Third party applications） を選択します。
3. 新しいアプリケーションを追加を選択し、次のパラメーターを使用してセットアップウィザードを完了します。
   • クライアントのタイプ： 機密クライアントを選択します。
   • 認可グラントのタイプ： クライアント認証情報の付与を有効にします。
4. サマリーページの右下にあるアプリケーションの登録を選択します。
5. 完了画面で、後の手順で必要になるクライアントIDを記録します。次に、アプリケーションの使用を有効にするを選択し、トグルスイッチで有効にするに切り替えます。

ステップ2：サードパーティアプリケーションのサービスユーザーに権限を付与する

前の手順でサードパーティアプリケーションを作成した際に、Foundry がサービスユーザーを自動的に作成しました。S3 API 経由でデータセットにアクセスするには、このサービスユーザーに、関連するプロジェクトとマーキングに対する十分な権限が必要です。

サービスユーザーの権限を設定するには、次の手順を実行します。

1. サービスユーザーの名前と ID を確認します。これらの情報は、アプリケーションの「アプリケーションの管理」ページの認可グラントのタイプ > クライアント認証情報の付与 > サービスユーザーで確認できます。
2. サービスユーザーをプロジェクトとマーキングに直接追加するか、それらの権限が付与されたグループに追加して、サービスユーザーに権限を付与します。

ステップ3：S3 アクセスキーIDとシークレットアクセスキーを生成する

アクセスキーIDとシークレットアクセスキーを取得するには、次のターミナルコマンドを実行します（curl または PowerShell を使用します）。コマンド内の次のプレースホルダーを置き換えます。

• <TOKEN>：ユーザーアカウントのアクティブなトークン。
• <CLIENT_ID>：前の手順で生成されたサードパーティアプリケーションのクライアントID。
• <PROJECT_RID>：資格情報でアクセスできるようにするプロジェクトのリソース識別子 (RID)。この値の確認方法については、以下のプロジェクトの RID を確認するを参照してください。

projectRestrictions の値には複数のプロジェクトを指定できるため、必要に応じてさらにプロジェクトの RID を列挙できます。プロジェクトを1つ以上指定する必要があります。生成された資格情報でアクセスできるのは、列挙したプロジェクト内に存在するデータセットのみです。

オプション1: curl

Copied!
1
2
3
4
5
curl -X POST \
    -H "Authorization: Bearer <TOKEN>" \
    -H "Content-type: application/json" \
    --data '{"clientId":"<CLIENT_ID>","projectRestrictions":["<PROJECT_RID>"]}' \
    https://<FOUNDRY_URL>/io/s3/api/v2/credentials

オプション2: PowerShell (Windows)

Copied!
1
2
3
4
5
6
7
8
9
10
$headers = @{
    "Authorization" = "Bearer <TOKEN>"
    "Content-type" = "application/json"
}
$body = @{
    "clientId" = "<CLIENT_ID>"
    "projectRestrictions" = @("<PROJECT_RID>")
} | ConvertTo-Json

Invoke-WebRequest -Uri "https://<FOUNDRY_URL>/io/s3/api/v2/credentials" -Method POST -Headers $headers -Body $body

このリクエストのレスポンスで受け取ったアクセスキーとシークレットキーを安全に保管してください。クライアントの設定には、サードパーティアプリケーションのクライアントIDとシークレット_ではなく_、これらの資格情報を使用する必要があります。

プロジェクトの RID を確認する

<PROJECT_RID> の値は、最上位のプロジェクトの RID である必要があり、プロジェクト内にネストされたフォルダーやその他のリソースの RID ではありません。プロジェクトとフォルダーはいずれも ri.compass.main.folder.{RID_VALUE} という RID 形式を使用するため、形式だけでは区別できません。

プロジェクトの RID を確認するには、次の手順を実行します。

1. 次のいずれかの方法でプロジェクトの RID をコピーします。
   • ワークスペースのナビゲーションサイドバーでファイルを選択し、プロジェクトタブを開きます。プロジェクトを右クリックし、RID をコピーを選択します。この一覧にはプロジェクトのみが含まれるため、この値がプロジェクト内のフォルダーのものであることはありません。個人フォルダ内のプロジェクトは一覧に表示されず、ゴミ箱に入れられたプロジェクトでは RID をコピーは利用できません。
   • プロジェクトを開き、ファイル一覧の上にあるアクションを選択してから、RID をコピーを選択します。アクションが表示されない場合は、一覧内の選択をすべてクリアします。
   • プロジェクトを開き、ページの空白領域を選択して、選択をすべてクリアします。すると、プロジェクト詳細パネルには、フォルダー内の項目ではなく、現在表示しているフォルダーの情報が表示されます。メタデータセクションの RID フィールドをコピーします。
2. アクションメニューと詳細パネルはいずれも現在開いているフォルダーに適用されるため、プロジェクトのルートを開きます。詳細パネルには情報の対象となるリソース名が表示されるため、その値がプロジェクトのものであることを確認できます。

projectRestrictions の値は、資格情報でアクセスできるデータセットを決定します。データセット内のファイルの書き込み先は制御しません。S3 バケットは Foundry データセットに対応するため、データセット内のファイルは、Foundry のフォルダーを対象として指定するのではなく、オブジェクトキー（論理ファイルパス）を使用して整理します。特定の場所にファイルを送信するには、宛先データセットをバケットとして選択し、logs/ などのキー接頭辞を使用してその中のファイルをグループ化します。

組織を指定する

デフォルトでは、/v2/credentials エンドポイントは、認証を行うユーザーが自身の組織内のサードパーティアプリケーション用に資格情報を生成していると想定します。サードパーティアプリケーションが別の組織に存在する場合は、URL のクエリパラメーターとして組織IDを指定します: https://<FOUNDRY_URL>/io/s3/api/v2/credentials?organizationRid=<ORGANIZATION_ID>。

資格情報を取り消す

アクセスキーとシークレットアクセスキーを取り消す必要がある場合は、次のエンドポイントを呼び出し、<ACCESS_KEY_ID> を取り消すアクセスキーIDに置き換えます。

Copied!
1
2
3
curl -X DELETE \
    -H "Authorization: Bearer <TOKEN>" \
    https://<FOUNDRY_URL>/io/s3/api/v2/credentials/<ACCESS_KEY_ID>

資格情報を一覧表示する

次のエンドポイントを使用すると、アクティブな（取り消し済みではない）アクセスキーの一覧を、クライアントIDおよびプロジェクト制限とともに取得できます。

Copied!
1
2
3
curl -X GET \
    -H "Authorization: Bearer <TOKEN>" \
    https://<FOUNDRY_URL>/io/s3/api/v2/credentials

ステップ4：S3 クライアントを設定する

S3 クライアントを設定するには、次の設定パラメーターを指定する必要があります。一般的な S3 クライアントでの設定方法については、以下の例を参照してください。

サポートされるアクション

次の S3 アクション ↗がサポートされています。

• AbortMultipartUpload ↗
• CompleteMultipartUpload ↗
• CopyObject ↗
• CreateMultipartUpload ↗
• DeleteObject ↗
• DeleteObjects ↗
• GetObject ↗
• HeadBucket ↗
• HeadObject ↗
• ListMultipartUploads ↗
• ListObjects ↗
• ListObjectsV2 ↗
• ListParts ↗
• PutObject ↗
• UploadPart ↗

クライアントのセットアップ例

前述のとおり、クライアント/SDK/コネクターがパス形式アクセスでバケットにアクセスするように設定されていることを確認してください。クライアントがバケットへのパス形式アクセスに対応していない場合、現時点ではこの API に対応していません。 たとえば、S3A Hadoop クライアント ↗では、 fs.s3a.path.style.access フラグを使用して設定できます。

一時的な資格情報を使用する場合は、AWS セッションアクセストークンも必ず設定してください。詳細については、該当する AWS クライアントのドキュメントを参照してください。たとえば、AWS CLI ↗ では、AWS_SESSION_TOKEN 環境変数を設定する必要があります。

AWS CLI

アクセスキーIDとシークレットアクセスキーを取得したら、AWS CLI ↗ を設定できます。次のコマンドを実行し、アクセスキーID、シークレットアクセスキー、リージョンを入力します。

$ aws configure --profile foundry
AWS Access Key ID [None]: <ACCESS_KEY_ID>
AWS Secret Access Key [None]: <SECRET_ACCESS_KEY>
Default region name [None]: foundry
Default output format [None]:

これで、foundry プロファイルを使用してコマンドを実行できるようになります。例：

Copied!
1
aws --profile foundry --endpoint-url https://<FOUNDRY_URL>/io/s3 s3 ls s3://<DATASET_RID>

AWS CLI の最近のリリース ↗により、profile 設定の一部として endpoint-url を設定できるようになりました。以下に、~/.aws/config に設定する foundry プロファイルのサンプルを示します。endpoint_url プロパティを使用してプロファイルを設定すると、aws コマンドの使用時に --endpoint-url 引数を指定する必要がなくなります。代わりに、--profile だけで十分です。

Copied!
1
2
3
[profile foundry]
region = foundry
endpoint_url = https://<FOUNDRY_URL>/io/s3

AWS CLI で一時的な資格情報を使用するには、CLI が AWS STS の AssumeRoleWithWebIdentity 呼び出しを行うように設定する方法を説明した AWS ドキュメント ↗に沿って進めてください。以下に、~/.aws/config に設定する foundry プロファイルのサンプルを示します。この設定を使用する場合、環境変数（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN）や ~/.aws/credentials に資格情報を設定しておく必要はありません。

Copied!
1
2
3
4
5
[profile foundry]
region = foundry
endpoint_url = https://<FOUNDRY_URL>/io/s3
web_identity_token_file = ~/.foundry/web-identity.token
role_arn=xxxxxxxxxxxxxxxxxxxx

上記の例では、有効な Foundry トークンが ~/.foundry/web-identity.token のファイルに保存されていることを前提としています。この方法は、このファイルが適切に保護され、漏えいのリスクがない場合にのみ推奨します。role_arn プロパティは使用されませんが、AWS CLI の検証により、指定が必須であり、20文字以上である必要があります。この例では、プレースホルダーとして xxxxxxxxxxxxxxxxxxxx を使用しています。この設定を使用するには、前述のとおり、--endpoint-url を使用するのではなく、~/.aws/config に endpoint_url を設定する必要があります。

AWS SDK for Python (Boto3)

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import boto3
import pandas as pd

s3 = boto3.client(
    's3',
    aws_access_key_id="<ACCESS_KEY_ID>",
    aws_secret_access_key="<SECRET_ACCESS_KEY>",
    # aws_session_token="<SESSION_TOKEN>", 一時的な資格情報を使用する場合にのみ必要です
    endpoint_url="https://<FOUNDRY_URL>/io/s3",
    region_name="foundry"
)

bucket = 'ri.foundry.main.dataset.<uuid>'
key = 'iris.csv'

obj = s3.get_object(Bucket=bucket, Key=key)
df = pd.read_csv(obj['Body'])
print(df)

Boto3 を使用して S3 に対応するソースに接続する方法の詳細については、Boto3 ドキュメントの S3 セクション ↗を参照してください。

Spark

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
from pyspark.sql import SparkSession

hostname = "https://<FOUNDRY_URL>/io/s3"
access_key_id = "<ACCESS_KEY_ID>"
secret_access_key = "<SECRET_ACCESS_KEY>"

# データセット RID を有効なホスト名としてパースできるようにしてください
dataset_rid = "ri.foundry.main.dataset.<uuid>".replace('.', '-')

spark_session = (
    SparkSession.builder
        .config("fs.s3a.access.key", access_key_id)
        .config("fs.s3a.secret.key", secret_access_key)
        # .config("fs.s3a.session.token", session_token) 一時的な資格情報を使用する場合にのみ必要です
        .config("fs.s3a.endpoint", hostname)
        .config("fs.s3a.endpoint.region", "foundry")
        .config("fs.s3a.path.style.access", "true")
        .getOrCreate()
)

df = spark_session.read.parquet(f"s3a://{dataset_rid}/*")
df.show()

Spark で S3 を使用する方法の詳細については、Spark ドキュメント ↗を参照してください。

Cyberduck

1. 次のプロファイルをダウンロードします。Foundry S3.cyberduckprofile ↗

2. プロファイルファイルをダブルクリックして開き、Cyberduck にプロファイルを登録します。

3. Cyberduck が作成したデフォルトのブックマークに、次の接続プロパティを設定します。

   • サーバー: https://<FOUNDRY_URL>
   • アクセスキーID: <ACCESS_KEY_ID>
   • シークレットアクセスキー: <SECRET_ACCESS_KEY>
   • パス:（追加オプション内）ri.foundry.main.dataset.<uuid>

4. ブックマークの設定ウィンドウを閉じます。

5. ブックマークをダブルクリックして接続を開きます。

S3 に対応するソースに接続する方法の詳細については、Cyberduck ドキュメント ↗を参照してください。

Google Storage Transfer Service

Google Cloud の Storage Transfer Service ↗ は、Foundry を S3 に対応するソース ↗として扱うことができます。以下の手順で、Foundry データセットから Cloud Storage バケットにデータを転送できます。

1. Google Cloud の手順 ↗に沿って、エージェントプールと転送エージェントをセットアップします。

2. 転送ジョブを作成し、ソースタイプとして S3 互換オブジェクトストレージを選択します。次に、ステップ（1）で作成したエージェントプールを選択し、次の設定が適用されていることを確認します。

   • バケット: ri.foundry.main.dataset.<uuid>。
   • エンドポイント: https://<FOUNDRY_URL>/io/s3
   • 署名リージョン: foundry
   • 署名プロセス： 署名バージョン4 (SigV4)
   • アドレス指定形式： パス形式アクセスのリクエスト
   • ネットワークプロトコル: HTTPS
   • 一覧取得 API バージョン: ListObjectsV2

セットアップを完了して、転送ジョブの Cloud Storage バケットの宛先、スケジュール、および設定を行います。

Apache NiFi

Apache NiFi を使用して、Foundry データセット内のファイルを読み書きできます。次の例は、書き込み用に PutS3Object プロセッサーの種類を設定する方法を示しています。

• オブジェクトキー： path/to/file.csv 形式の、データセット内の論理ファイルパス
• バケット： ri.foundry.main.dataset.<uuid> などのデータセット RID
• アクセスキーID: <ACCESS_KEY_ID>
• シークレットアクセスキー: <SECRET_ACCESS_KEY>
• リージョン： us-east-1 に対応する「米国東部（バージニア北部）」
• パス形式アクセスを使用: true
• エンドポイントのオーバーライド URL: https://<FOUNDRY_URL>/io/s3

PutS3Object プロセッサーや、S3 に対応するソースをサポートするほかのプロセッサーの詳細については、Apache NiFi ドキュメント ↗を参照してください。

Airbyte

Airbyte ↗ の S3 宛先のサポートを利用して、Foundry データセットにファイルを書き込むことができます。次の宛先設定を行います。

• 宛先タイプ: S3
• S3 キーID: <ACCESS_KEY_ID>
• S3 アクセスキー: <SECRET_ACCESS_KEY>
• S3 バケット名: ri.foundry.main.dataset.<uuid>
• S3 バケットパス： 任意の有効なサブディレクトリパス。Airbyte は、Foundry データセット内のこのサブディレクトリにファイルを書き込みます。
• S3 バケットリージョン: us-east-1
• 出力形式： Airbyte のすべての出力形式は、Foundry データセットに対応しています。
• エンドポイント: https://<FOUNDRY_URL>/io/s3

詳細および設定オプションについては、Airbyte の S3 宛先に関するドキュメント ↗を参照してください。

DuckDB

DuckDB ↗ の S3 サポートを利用して、Foundry データセットをクエリできます。DuckDB のシークレットを使用して資格情報を管理し、s3:// をプレフィックスとする URL を使用してデータセットをクエリできます。

CREATE SECRET foundry_secret (
    TYPE S3,
    KEY_ID '<ACCESS_KEY_ID>',
    SECRET '<SECRET_ACCESS_KEY>',
    REGION 'foundry',
    ENDPOINT '<FOUNDRY_URL>/io/s3',
    URL_STYLE 'path'
);

CREATE TABLE new_tbl AS SELECT * FROM 's3://ri.foundry.main.dataset.<uuid>/spark/*.parquet';

詳細については、DuckDB ドキュメント ↗を参照してください。

Polars

Polars ↗ の S3 サポートを利用して、Foundry データセットをクエリできます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import polars as pl

hostname = "https://<FOUNDRY_URL>/io/s3"
access_key_id = "<ACCESS_KEY_ID>"
secret_access_key = "<SECRET_ACCESS_KEY>"
dataset_rid = "ri.foundry.main.dataset.<uuid>"

storage_options = {
    "aws_access_key_id": access_key_id,
    "aws_secret_access_key": secret_access_key,
    "aws_region": "foundry",
    "endpoint_url": hostname
}

df = pl.scan_parquet(f"s3://{dataset_rid}/spark/*.parquet", storage_options=storage_options)

詳細については、Polars ドキュメント ↗を参照してください。