スキルOfficialdevelopment

💾aidp-object-storage

プラグイン: oracle-ai-data-platform-workbench-spark-connectors
ソース: GitHub で見る ↗

説明

`oci://` URIスキームを使用して、AIDPノートブックからOCI Object Storageをネイティブに読み書きします。次のような場合に使用: - ユーザーがOCI Object StorageやURIスキーム `oci://` に言及している - 外部ボリュームやObject Storageを基盤とする外部テーブルを扱いたい - バケット内のCSV / Parquet / JSON / Deltaファイルを操作したい - データをOCIバケットに書き出したい認証はワークスペースのIAMアイデンティティを通じて暗黙的に行われるため、ノートブック内にキーを記述する必要はありません。

原文を表示

Read and write OCI Object Storage natively from an AIDP notebook using the `oci://` URI scheme. Use when the user mentions OCI Object Storage, "oci://", external volumes, external tables backed by Object Storage, CSV/Parquet/JSON/Delta files in a bucket, or wants to land data in OCI buckets. Auth is implicit via the workspace's IAM identity — no keys in the notebook.

ユースケース

✓oci:// URIスキームを使用したい
✓Object Storageからデータを読み書きする
✓CSV/Parquet/JSON/Deltaファイルを操作したい
✓OCIバケットにデータを書き出したい

本文（日本語訳）

`aidp-object-storage` — OCI Object Storage ネイティブ対応（`oci://`）

SparkからObject Storageのデータを直接読み書きします。 AIDPクラスターのIAMアイデンティティが自動的に使用されるため、OCI_CONFIG、APIキー、インラインPEMは一切不要です。

次のような場合に使用

SparkからOCIバケットへCSV / Parquet / JSON / Avro / Deltaファイルを書き込む、または読み込む。
OCIバケットをバッキングストアとした External Volume（/Volumes/...）を登録する。
oci:// パスを参照する External Table（USING CSV/PARQUET/...）を定義する。
「oci://」「Object Storageバケット」「external volume」「external table」というキーワードが登場する。

次のような場合は使用しない

OCI Object Storage上の Iceberg テーブルを扱う場合 → aidp-iceberg を使用。
AWS S3 を扱う場合 → aidp-aws-s3 を使用。
Azure ADLS Gen2 を扱う場合 → aidp-azure-adls を使用。

URI形式

oci://<bucket>@<namespace>/<path>

namespaceとはテナンシーのObject Storageネームスペースを指します（OCI Console > Object Storage > バケット詳細で確認可能）。

直接読み書き

oci_path = "oci://my-bucket@mynamespace/folder/file"

# 書き込み
df.write.mode("overwrite").option("header", True).format("csv").save(oci_path)

# 読み込み
df_read = spark.read.option("header", True).format("csv").load(oci_path)
df_read.show()

format("parquet")、format("json")、format("delta") でも同様のパターンで使用できます。

External Volume（DDL）

バケットを一度マウントしておけば、以降はVolumeパスで永続的に参照できます。

CREATE EXTERNAL VOLUME IF NOT EXISTS default.default.ext_volume
LOCATION 'oci://my-bucket@mynamespace/';

登録後の利用:

volume_path = "/Volumes/default/default/ext_volume/folder/file"
df.write.format("csv").option("header", True).save(volume_path)
spark.read.option("header", True).format("csv").load(volume_path).show()

削除する場合: DROP VOLUME default.default.ext_volume

External Table（DDL）

データを oci:// 上に保持するテーブルを登録します。

CREATE TABLE IF NOT EXISTS default.default.ext_table (name STRING, age INT)
USING CSV
OPTIONS (path='oci://my-bucket@mynamespace/folder/file', delimiter=',', header='true');

通常のSparkテーブルと同様にクエリ実行できます:

spark.sql("SELECT * FROM default.default.ext_table").show()

削除する場合: DROP TABLE default.default.ext_table

注意事項

認証は暗黙的 — AIDPクラスターのIAMアイデンティティが使用されます。ユーザーがOCIキーを入力する必要はありません。404 / 403エラーで読み込みに失敗する場合は、ワークスペースのアイデンティティにバケットへのアクセス権限がないため、OCI IAM側で権限を修正してください。
namespace ≠ テナンシー名。 Object Storageネームスペースはテナンシー名とは別の、変更不可能な固有の文字列です。OCI Console > プロフィール > テナンシー: <tenancy_name> の object_storage_namespace フィールドで確認できます。
External VolumeのパスはVolumeパス（/Volumes/<catalog>/<schema>/<volume>/...） であり、oci://... ではありません。Volumeを登録した後は、ファイルへのアクセスにはVolumeパスを使用してください。
External Tableの path オプションには oci:// を直接指定します。 Volumeパスではありません。どちらの方式も機能しますが、再マウント可能な抽象化が必要な場合はVolume、シンプルな直接参照で十分な場合はTableを選択してください。
/Workspace/... はデータ用ではありません。 ノートブックや設定ファイル向けのFUSEマウントファイルシステムです。データファイルには oci:// または /Volumes/... を使用してください。

参考資料

公式サンプル: oracle-samples/oracle-aidp-samples → getting-started/Access_Object_Storage_Data.ipynb

原文（English）を表示

`aidp-object-storage` — OCI Object Storage native (`oci://`)

Read and write Object Storage data directly from Spark. The AIDP cluster's IAM identity is used automatically — no OCI_CONFIG, no API keys, no inline PEM.

When to use

Land or read CSV / Parquet / JSON / Avro / Delta files in an OCI bucket from Spark.
Register an External Volume (/Volumes/...) backed by an OCI bucket.
Define an External Table (USING CSV/PARQUET/...) over an oci:// path.
Mentioned: "oci://", "Object Storage bucket", "external volume", "external table".

When NOT to use

For Iceberg tables on OCI Object Storage → use aidp-iceberg.
For AWS S3 → use aidp-aws-s3.
For Azure ADLS Gen2 → use aidp-azure-adls.

URI form

oci://<bucket>@<namespace>/<path>

The namespace is the tenancy's Object Storage namespace (OCI Console > Object Storage > Bucket Details).

Direct read/write

oci_path = "oci://my-bucket@mynamespace/folder/file"

# Write
df.write.mode("overwrite").option("header", True).format("csv").save(oci_path)

# Read
df_read = spark.read.option("header", True).format("csv").load(oci_path)
df_read.show()

Same pattern with format("parquet"), format("json"), format("delta").

External Volume (DDL)

Mount a bucket once, reference by Volume path forever:

CREATE EXTERNAL VOLUME IF NOT EXISTS default.default.ext_volume
LOCATION 'oci://my-bucket@mynamespace/';

Then:

volume_path = "/Volumes/default/default/ext_volume/folder/file"
df.write.format("csv").option("header", True).save(volume_path)
spark.read.option("header", True).format("csv").load(volume_path).show()

Drop with DROP VOLUME default.default.ext_volume.

External Table (DDL)

CREATE TABLE IF NOT EXISTS default.default.ext_table (name STRING, age INT)
USING CSV
OPTIONS (path='oci://my-bucket@mynamespace/folder/file', delimiter=',', header='true');

Query like any Spark table:

spark.sql("SELECT * FROM default.default.ext_table").show()

Drop with DROP TABLE default.default.ext_table.

Gotchas

Auth is implicit — the AIDP cluster's IAM identity is used. The user never types OCI keys. If reads fail with 404/403, the workspace identity lacks bucket privileges; fix in OCI IAM.
Namespace ≠ tenancy name. The Object Storage namespace is a separate, immutable string. Find it in OCI Console > Profile > Tenancy: <tenancy_name> — the object_storage_namespace field.
External volume path is /Volumes/<catalog>/<schema>/<volume>/..., NOT oci://.... Once a volume is registered, address files via the Volume path.
External table path option uses oci:// directly, not the Volume path. Both work; choose based on whether you want a re-mountable abstraction (Volume) or a simple direct reference (Table).
/Workspace/... is NOT for data. It's a FUSE-mounted file system intended for notebooks/configs. For data files use oci:// or /Volumes/....

References

Official sample: oracle-samples/oracle-aidp-samples → getting-started/Access_Object_Storage_Data.ipynb

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。