Lance REST Namespace API の互換性 - Object Storage Service - Alibaba Cloud ドキュメントセンター

OSS Tables は、Lance REST Namespace と互換性のある API エンドポイントを提供します。このトピックでは、API、パラメーター、認証の 3 つのディメンションから、リクエストパラメーター、応答フィールド、動作セマンティクスの観点で OSS Tables と Lance Namespace 標準プロトコルの違いについて説明します。この情報は、カスタムクライアントを開発したり、コンピュートエンジンを選択したりする際に、互換性範囲を評価するのに役立ちます。

互換性の設計原則

OSS Tables の Lance REST Namespace API は、以下の設計原則に従います：

標準プロトコルを優先：可能な限り、API、パラメーター、および応答セマンティクスは Lance REST Namespace 仕様に従って実装されます。TableBucket モデルによって制約される機能については、その違いと制限が明示的にリストされています。
TableBucket リソースモデルに従う：名前空間、テーブル、およびストレージロケーションはサーバーによって管理されます。単一レベルの名前空間のみがサポートされており、RegisterTable を使用して任意の既存のストレージロケーションを登録することはサポートされていません。
V4 署名認証を統一的に使用：AWS SigV4 と OSS V4 がサポートされています。署名サービス名は osstables で、OSS Tables の権限システムが使用されます。認証情報ベンディングはサポートされておらず、クライアントは独自のデータアクセス認証情報を設定する必要があります。
Lance ネイティブバージョン管理を使用：データセットバージョンは、名前空間で管理されるバージョン管理メカニズムではなく、Lance によって管理されます。managed_versioning は false を返します。

アクセスエンドポイントとリソース識別子

OSS Tables は Lance REST Namespace エンドポイントを提供します。Lance クライアントはこれらのエンドポイントを使用して、名前空間、テーブル、およびテーブルメタデータを管理します。各エンドポイントはテーブルバケットに対応します。クライアントが接続する際には、テーブルバケット名、バケットが属する Alibaba Cloud アカウント、およびリージョンを指定する必要があります。エンドポイントのフォーマットは次のとおりです：

ネットワークタイプ	エンドポイント
パブリックネットワーク	`https://{tableBucketName}-{uid}.{region}.oss-tables.aliyuncs.com/lance`
内部ネットワーク	`https://{tableBucketName}-{uid}.{region}-internal.oss-tables.aliyuncs.com/lance`

tableBucketName：テーブルバケット名、uid：Alibaba Cloud アカウントの UID、region：リージョン ID。
テーブルバケットが存在するリージョンの第 3 レベルドメイン名 ({tableBucketName}-{uid} プレフィックス) を使用する必要があります。リージョンドメイン名のみの使用はサポートされていません。第 3 レベルドメイン名のプレフィックスがない場合、LanceThirdLevelDomainRequired エラーが返されます。
テーブルバケット ARN をパスやリソース識別子に追加する必要はありません。

API パス内の {id} は、名前空間またはテーブルを識別します。これは、SDK 内の識別子配列の各部分を delimiter で結合して形成されます。デフォルトのデリミタは $ であり、URL パスの一部として渡す場合は URL エンコードする必要があります。以下の例はすべてデフォルトのデリミタを使用しています。

リソース	SDK 内の識別子配列	REST パス内の識別子の例
ルート名前空間	空の配列 (長さ 0)	`$`、エンコード後は `%24`
名前空間	`["my_db"]`	`my_db`
テーブル	`["my_db", "my_table"]`	`my_db$my_table`、エンコード後は `my_db%24my_table`

以降のセクションの API パスは、すべて上記のエンドポイントからの相対パスです。実際のリクエスト URL は、エンドポイントと API パスを連結して形成されます。たとえば、my_table テーブルを my_db 名前空間でクエリするためのリクエスト URL は https://{tableBucketName}-{uid}.{region}.oss-tables.aliyuncs.com/lance/v1/table/my_db%24my_table/describe です。

一般的な互換性の制約

以下の制約は関連する API に適用され、後続の API テーブルでは繰り返されません。

項目	互換性
名前空間レベル	単一レベルの名前空間のみがサポートされています。複数レベルの名前空間およびルート名前空間直下のテーブルはサポートされていません。
名前空間プロパティ	カスタム名前空間プロパティはサポートされていません。関連する応答の `properties` は `null` を返します。
`delimiter`	デフォルト値は `$` です。デリミタに `/`、`:`、または `-` を含めることはできません。
ページネーションパラメーター	`page_token` は Lance Namespace 仕様に準拠しています。`limit` の範囲は 1 から 1000 で、デフォルト値は 1000 です。
`context`	カスタムビジネスコンテキストは処理されません。
トランザクション	`transaction_id` は返されません。非同期トランザクションとその進捗クエリはサポートされていません。
バージョン管理	Lance ネイティブバージョン管理が使用されます。`managed_versioning` は `false` に固定されます。名前空間で管理されるバージョン管理はサポートされていません。

API の互換性

以下の表は、OSS Tables が現在サポートしている 14 の Lance Namespace 標準 API (5 つの名前空間 API と 9 つのテーブル API) を示しています。記載されていない標準 API はサポートされていません。

表中の「パス」と「メソッド」は REST リクエストの構築に使用され、「操作」は標準の Lance Namespace 操作名に対応します。「互換性」列には、各 API のパラメーター制約、応答の違い、および動作の制約が記載されています。上記の一般的な制約以外に違いがない API は、「Lance Namespace 仕様に準拠」とマークされています。

名前空間 API

パス	メソッド	操作	互換性
`/lance/v1/namespace/{id}/create`	POST	`CreateNamespace`	ルート名前空間の作成はサポートされていません。`mode=Overwrite` はサポートされていません。
`/lance/v1/namespace/{id}/list`	GET	`ListNamespaces`	Lance Namespace 仕様に準拠しています。
`/lance/v1/namespace/{id}/describe`	POST	`DescribeNamespace`	Lance Namespace 仕様に準拠しています。
`/lance/v1/namespace/{id}/exists`	POST	`NamespaceExists`	Lance Namespace 仕様に準拠しています。
`/lance/v1/namespace/{id}/drop`	POST	`DropNamespace`	ルート名前空間の削除はサポートされていません。`behavior=Cascade` (カスケード削除) はサポートされていません。空の名前空間のみ削除できます。

テーブル API

パス	メソッド	操作	互換性
`/lance/v1/namespace/{id}/table/list`	GET	`ListTables`	`tables` は、名前空間を含む完全修飾識別子ではなく、テーブル名のみを返します。`include_declared=true` のみがサポートされています。ルート名前空間を介したすべてのテーブルの再帰的な一覧表示はサポートされていません。複数の名前空間にまたがってテーブルを一覧表示するには、`ListAllTables` を使用します。
`/lance/v1/table`	GET	`ListAllTables`	`include_declared=true` のみがサポートされています。
`/lance/v1/table/{id}/create`	POST	`CreateTable`	`mode=Overwrite` はサポートされていません。Arrow IPC リクエストボディのデフォルトの上限は 10 MiB です。`storage_options` クエリパラメーターは無視されます。テーブルが `DeclareTable` を使用して宣言されただけで、Lance データセットが作成されていない場合、`CreateTable(mode=ExistOk)` は既存のテーブルを保持し、データセットを作成せず、`version=0` を返します。
`/lance/v1/table/{id}/declare`	POST	`DeclareTable`	空でない `location` の指定は許可されていません。ストレージロケーションはサーバーによって割り当てられます。
`/lance/v1/table/{id}/describe`	POST	`DescribeTable`	`version` と `branch` は、`load_detailed_metadata=true` または `check_declared=true` が指定されている場合にのみ有効です。それ以外の場合、ターゲットバージョンまたはブランチの存在は検証されません。`tag` を使用したタグバージョンの指定はサポートされていません。
`/lance/v1/table/{id}/exists`	POST	`TableExists`	Lance Namespace 仕様に準拠しています。
`/lance/v1/table/{id}/drop`	POST	`DropTable`	テーブルデータはバックグラウンドでクリーンアップされます。API 呼び出しが成功しても、物理データがクリーンアップされたことを示すものではありません。
`/lance/v1/table/{id}/rename`	POST	`RenameTable`	Lance Namespace 仕様に準拠しています。
`/lance/v1/table/{id}/deregister`	POST	`DeregisterTable`	Lance Namespace 仕様に準拠しています。詳細については、以下の DeregisterTable の実装に関する注意点をご参照ください。

DeregisterTable の実装に関する注意点

DeregisterTable はテーブルの登録を解除するために使用され、データは削除しません。処理ロジックは次のとおりです：

テーブルはシステム予約の名前空間 oss-deregistered-ns に移動されます。
テーブル名は oss-deregistered-table-{tableId} に変更されます。ここで、tableId は元のテーブル ID です。元のテーブル名は再利用できます。
ListNamespaces は予約された名前空間をリストせず、ListAllTables は登録解除されたテーブルをリストしません。
ListTables を呼び出して oss-deregistered-ns をリストし、登録解除されたテーブルを表示します。
テーブルを完全に削除するには、一覧表示操作で返された予約された名前空間とテーブル名を使用して DropTable を呼び出します。これにより、テーブルとそのデータが削除されます。

認証メカニズムと権限

OSS Tables の Lance REST Namespace API は、AWS SigV4 および OSS V4 署名認証のみをサポートします。署名サービス名またはプロダクト名は osstables で、署名リージョンはテーブルバケットが存在するリージョンです。OAuth2、Bearer トークン、および API キー認証はサポートされていません。

認証方法	互換性
AWS SigV4	サポート (推奨)。署名サービス名は `osstables` で、署名リージョンはテーブルバケットが存在するリージョンです。
OSS V4	サポートされています。OSS V4 署名ルールを使用します。署名プロダクト名は `osstables` です。
OAuth2、Bearer トークン、`x-api-key`	サポートされていません。OSS Tables のリクエスト署名を使用する必要があります。
認証情報ベンディング	`DescribeTable` および `DeclareTable` は `vend_credentials=true` をサポートしていません。ストレージ認証情報はベンディングされず、応答は `storage_options` を返しません。クライアントは独自のストレージアクセス認証情報を設定する必要があります。