バージョン: 4.1 GA

Microsoft Azure Storage への認証

バージョン 3.0 以降、StarRocks は以下のシナリオで Microsoft Azure Storage (Azure Blob Storage または Azure Data Lake Storage) と統合できます。

Azure Storage 内の Hive、Iceberg、Hudi、および Delta Lake テーブルのクエリ。
Azure Storage からのバッチデータのロード。

次の表は、Azure Storage の種類ごとに StarRocks がサポートする認証方法を示しています。

Azure Storage の種類	認証方法
Azure Blob Storage	共有キー (ストレージアカウントのアクセスキー) SAS トークン
Azure Data Lake Storage Gen2 (ADLS Gen2)	マネージド ID 共有キー (ストレージアカウントのアクセスキー) サービスプリンシパル
Azure Data Lake Storage Gen1 (ADLS Gen1)、廃止済み	マネージドサービス ID サービスプリンシパル

マネージド ID 認証方法では、クラスターマネージド ID を使用します。このトピックでは、クラスターマネージド ID とは、PhoenixAI クラスターのデータ資格情報で参照されているユーザー割り当てマネージド ID を指します。

External catalog の場合は、外部データソースのデータを格納しているストレージアカウントの認証情報を使用します。

このトピックでは、Hive catalog および Broker Load を例として使用します。Broker Load の例では、データファイル file1.parquet をデータベース mydatabase のテーブル table1 にロードします。file1.parquet と table1 のスキーマは同じです。例のパラメータについては、Hive catalog および Broker Load を参照してください。

Blob Storage

StarRocks は、Blob Storage にアクセスするために次の認証方法のいずれかを使用することをサポートしています。

共有キー
SAS トークン

注意

Blob Storage からデータをロードしたり、ファイルを直接クエリしたりする場合、データにアクセスするために wasb または wasbs プロトコルを使用する必要があります。

ストレージアカウントが HTTP 経由でのアクセスを許可する場合、wasb プロトコルを使用し、ファイルパスを wasb://<container>@<storage_account>.blob.core.windows.net/<path>/<file_name> として記述します。

ストレージアカウントが HTTPS 経由でのアクセスを許可する場合、wasbs プロトコルを使用し、ファイルパスを wasbs://<container>@<storage_account>.blob.core.windows.net/<path>/<file_name> として記述します。

共有キー (ストレージアカウントのアクセスキー)

アクセスキーは、StarRocks クラスターがストレージアカウントに送信するリクエストを認証します。アクセスキーの詳細については、Manage account access keys - Azure Storage を参照してください。

パラメータ

パラメータ	説明
azure.blob.storage_account	Blob Storage のストレージアカウントの名前。
azure.blob.shared_key	Blob Storage のストレージアカウントの共有キー (アクセスキー)。

Blob Storage のストレージアカウントの共有キーを取得するには、次の手順に従います。

Azure portal にサインインし、Storage accounts ページに移動します。
ストレージアカウントを見つけて、その名前をクリックします。
左側のナビゲーションペインで、Access keys を選択します。
使用するキーの横にある Show をクリックし、コピーアイコンをクリックしてキーをコピーします。

例

External catalog

azure.blob.storage_account と azure.blob.shared_key を CREATE EXTERNAL CATALOG ステートメントで次のように設定します。

CREATE EXTERNAL CATALOG hive_catalog_azure
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.blob.storage_account" = "<blob_storage_account_name>",
    "azure.blob.shared_key" = "<blob_storage_account_shared_key>"
);

Broker Load

azure.blob.storage_account、azure.blob.shared_key、およびファイルパス (DATA INFILE) を LOAD LABEL ステートメントで次のように設定します。

LOAD LABEL mydatabase.label_blob_key
(
    DATA INFILE("wasb[s]://<container>@<storage_account>.blob.core.windows.net/<path>/file1.parquet")
    INTO TABLE table1
    FORMAT AS "parquet"
)
WITH BROKER
(
    "azure.blob.storage_account" = "<blob_storage_account_name>",
    "azure.blob.shared_key" = "<blob_storage_account_shared_key>"
);

SAS トークン

共有アクセス署名 (SAS) は、ストレージアカウントへの制限付きアクセスを許可するトークンです。SAS トークンの詳細については、Delegate access by using a shared access signature - Azure Storage を参照してください。

パラメータ

パラメータ	説明
azure.blob.storage_account	Blob Storage のストレージアカウントの名前。
azure.blob.container	Blob Storage のストレージアカウント内でデータを格納している Blob コンテナの名前。
azure.blob.sas_token	Blob Storage のストレージアカウントへのアクセスに使用する SAS トークン。

Blob Storage のストレージアカウントの SAS トークンを取得するには、次の手順に従います。

Azure portal にサインインし、Storage accounts ページに移動します。
ストレージアカウントを見つけて、その名前をクリックします。
左側のナビゲーションペインで、Shared access signature を選択します。
Allowed services、Allowed resource types、および Allowed permissions セクションの設定を確認します。次に、Signing key ドロップダウンリストからキーを選択し、Generate SAS and connection string をクリックします。
コピーアイコンをクリックして、生成された SAS トークンをコピーします。

例

External catalog

azure.blob.storage_account、azure.blob.container、および azure.blob.sas_token を CREATE EXTERNAL CATALOG ステートメントで次のように設定します。

CREATE EXTERNAL CATALOG hive_catalog_azure
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.blob.storage_account" = "<blob_storage_account_name>",
    "azure.blob.container" = "<blob_container_name>",
    "azure.blob.sas_token" = "<blob_storage_account_SAS_token>"
);

Broker Load

azure.blob.storage_account、azure.blob.container、azure.blob.sas_token、およびファイルパス (DATA INFILE) を LOAD LABEL ステートメントで次のように設定します。

LOAD LABEL mydatabase.label_blob_sas
(
    DATA INFILE("wasb[s]://<container>@<storage_account>.blob.core.windows.net/<path>/file1.parquet")
    INTO TABLE table1
    FORMAT AS "parquet"
)
WITH BROKER
(
    "azure.blob.storage_account" = "<blob_storage_account_name>",
    "azure.blob.container" = "<blob_container_name>",
    "azure.blob.sas_token" = "<blob_storage_account_SAS_token>"
);

Data Lake Storage Gen2

StarRocks は、Data Lake Storage Gen2 にアクセスするために次の認証方法のいずれかを使用することをサポートしています。

マネージド ID
共有キー
サービスプリンシパル

注意

Data Lake Storage Gen2 からデータをロードしたり、ファイルをクエリしたりする場合、データにアクセスするために abfs または abfss プロトコルを使用する必要があります。

ストレージアカウントが HTTP 経由でのアクセスを許可する場合、abfs プロトコルを使用し、ファイルパスを abfs://<container>@<storage_account>.dfs.core.windows.net/<path>/<file_name> として記述します。

ストレージアカウントが HTTPS 経由でのアクセスを許可する場合、abfss プロトコルを使用し、ファイルパスを abfss://<container>@<storage_account>.dfs.core.windows.net/<path>/<file_name> として記述します。

マネージド ID

ユーザー割り当てマネージド ID を使用すると、VM などの Azure リソースは、認証情報を保存することなく他の Azure サービスに対して認証できます。ユーザー割り当てマネージド ID は、スタンドアロンの Azure リソースです。1 台の VM で複数のユーザー割り当てマネージド ID を使用でき、1 つのユーザー割り当てマネージド ID を複数の VM で共有できます。

この方法では、StarRocks はクラスターマネージド ID を使用してストレージアカウントにアクセスします。

準備

この認証方法を使用する前に、クラスターマネージド ID が存在し、ストレージアカウントに対して必要な権限を持っていることを確認してください。

まず、クラスターマネージド ID の名前を確認します。

PhoenixAI Cloud コンソールにサインインします。
Clusters ページで、PhoenixAI クラスターを見つけてクリックします。
Cloud settings タブで、Data credential セクションに移動し、Managed identity resource ID を見つけます。リソース ID の最後の要素が、クラスターマネージド ID の名前です。たとえば、Managed identity resource ID が /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/celerdata-20240426-resource-group-001/providers/Microsoft.ManagedIdentity/userAssignedIdentities/celerdata-20240426-managed-identity の場合、クラスターマネージド ID の名前は celerdata-20240426-managed-identity です。

次に、クラスターマネージド ID がストレージアカウントに対して必要な権限を持っていることを確認します。

Azure portal にサインインし、Storage accounts ページに移動します。
ストレージアカウントを見つけて、その名前をクリックします。
左側のナビゲーションペインで、Access control (IAM) を選択します。
Role assignments タブで、既存のロールの割り当てを確認します。
クラスターマネージド ID がストレージアカウントに対して必要な権限を持っていない場合は、Add をクリックして Add role assignment を選択します。次に、ロールの割り当てを追加します。

a. Job function roles タブでロールを選択し、Next をクリックします。たとえば、Storage Blob Data Reader は読み取りアクセスを付与し、Storage Blob Data Contributor は読み取りと書き込みのアクセスを付与します。

b. Members タブで、Assign access to に Managed identity を選択します。

c. Members で Select members をクリックします。表示されたペインでサブスクリプションを選択し、Managed identity ドロップダウンリストから User-assigned managed identity を選択し、クラスターマネージド ID を選択して、Select をクリックします。

d. Review + assign をクリックします。情報を確認し、もう一度 Review + assign をクリックしてロールの割り当てを追加します。

パラメータ

パラメータ	説明
azure.adls2.oauth2_use_managed_identity	マネージド ID 認証方法を有効にするかどうかを指定します。値を `true` に設定します。
azure.adls2.oauth2_tenant_id	ADLS Gen2 ストレージアカウントのテナントの ID。
azure.adls2.oauth2_client_id	クラスターマネージド ID のクライアント ID。

テナント ID を取得するには、次の手順に従います。

Azure portal にサインインし、Tenant properties ページに移動します。
Tenant ID を見つけ、コピーアイコンをクリックしてコピーします。

クラスターマネージド ID のクライアント ID を取得するには、次の手順に従います。

Azure portal にサインインし、Managed Identities ページに移動します。
クラスターマネージド ID を見つけて、その名前をクリックします。
Overview ページで Client ID を見つけ、コピーアイコンをクリックしてコピーします。

例

External catalog

azure.adls2.oauth2_use_managed_identity、azure.adls2.oauth2_tenant_id、および azure.adls2.oauth2_client_id を CREATE EXTERNAL CATALOG ステートメントで次のように設定します。

CREATE EXTERNAL CATALOG hive_catalog_azure
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls2.oauth2_use_managed_identity" = "true",
    "azure.adls2.oauth2_tenant_id" = "<tenant_id>",
    "azure.adls2.oauth2_client_id" = "<managed_identity_client_id>"
);

Broker Load

azure.adls2.oauth2_use_managed_identity、azure.adls2.oauth2_tenant_id、azure.adls2.oauth2_client_id、およびファイルパス (DATA INFILE) を LOAD LABEL ステートメントで次のように設定します。

LOAD LABEL mydatabase.label_gen2_identity
(
    DATA INFILE("abfs[s]://<container>@<storage_account>.dfs.core.windows.net/<path>/file1.parquet")
    INTO TABLE table1
    FORMAT AS "parquet"
)
WITH BROKER
(
    "azure.adls2.oauth2_use_managed_identity" = "true",
    "azure.adls2.oauth2_tenant_id" = "<tenant_id>",
    "azure.adls2.oauth2_client_id" = "<managed_identity_client_id>"
);

共有キー (ストレージアカウントのアクセスキー)

共有キーを使用して ADLS Gen2 にアクセスする方法は、共有キーを使用して Blob Storage にアクセスする方法と同じです。共有キーの取得方法については、Blob Storage > 共有キーを参照してください。

パラメータ

パラメータ	説明
azure.adls2.storage_account	ADLS Gen2 ストレージアカウントの名前。
azure.adls2.shared_key	ADLS Gen2 ストレージアカウントの共有キー (アクセスキー)。

例

External catalog

azure.adls2.storage_account と azure.adls2.shared_key を CREATE EXTERNAL CATALOG ステートメントで次のように設定します。

CREATE EXTERNAL CATALOG hive_catalog_azure
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls2.storage_account" = "<storage_account_name>",
    "azure.adls2.shared_key" = "<shared_key>"
);

Broker Load

azure.adls2.storage_account、azure.adls2.shared_key、およびファイルパス (DATA INFILE) を LOAD LABEL ステートメントで次のように設定します。

LOAD LABEL mydatabase.label_gen2_key
(
    DATA INFILE("abfs[s]://<container>@<storage_account>.dfs.core.windows.net/<path>/file1.parquet")
    INTO TABLE table1
    FORMAT AS "parquet"
)
WITH BROKER
(
    "azure.adls2.storage_account" = "<storage_account_name>",
    "azure.adls2.shared_key" = "<shared_key>"
);

サービスプリンシパル

準備

この認証方法を使用する前に、サービスプリンシパルがあり、そのサービスプリンシパルがストレージアカウントに対して必要な権限を持っていることを確認してください。サービスプリンシパルとクライアントシークレットの作成方法については、Register a Microsoft Entra app and create a service principal を参照してください。

注記

サービスプリンシパルは、PhoenixAI クラスターのデプロイに使用されたものである必要があります。

サービスプリンシパルの権限を確認するには、次の手順に従います。

Azure portal にサインインし、Storage accounts ページに移動します。
ADLS Gen2 ストレージアカウントを見つけて、その名前をクリックします。
左側のナビゲーションペインで、Access control (IAM) を選択します。
Role assignments タブで、既存のロールの割り当てを確認します。
サービスプリンシパルがストレージアカウントに対して必要な権限を持っていない場合は、Add をクリックして Add role assignment を選択します。次に、ロールの割り当てを追加します。

a. Job function roles タブでロールを選択し、Next をクリックします。たとえば、Storage Blob Data Reader は読み取りアクセスを付与し、Storage Blob Data Contributor は読み取りと書き込みのアクセスを付与します。

b. Members タブで、Assign access to に User, group, or service principal を選択します。

c. Members で Select members をクリックします。表示されたペインで、登録したアプリケーションを検索して選択し、Select をクリックします。

d. Review + assign をクリックします。情報を確認し、もう一度 Review + assign をクリックしてロールの割り当てを追加します。

パラメータ

パラメータ	説明
azure.adls2.oauth2_client_id	サービスプリンシパルのアプリケーション (クライアント) ID。
azure.adls2.oauth2_client_secret	サービスプリンシパルのクライアントシークレットの値。
azure.adls2.oauth2_client_endpoint	サービスプリンシパルの OAuth 2.0 トークンエンドポイント (v1)。

注意

Azure は、クライアントシークレットの値を作成直後に一度だけ表示します。ページを離れる前に値を保存してください。

サービスプリンシパルのアプリケーション (クライアント) ID と OAuth 2.0 トークンエンドポイント (v1) を取得するには、次の手順に従います。

Azure portal にサインインし、App registrations ページに移動します。
登録したアプリケーションを見つけて、その名前をクリックします。
Overview ページで Application (client) ID を見つけ、コピーアイコンをクリックしてコピーします。
Overview ページの上部にある Endpoints をクリックします。
Endpoints ペインで OAuth 2.0 token endpoint (v1) を見つけ、コピーアイコンをクリックしてコピーします。

例

External catalog

azure.adls2.oauth2_client_id、azure.adls2.oauth2_client_secret、および azure.adls2.oauth2_client_endpoint を CREATE EXTERNAL CATALOG ステートメントで次のように設定します。

CREATE EXTERNAL CATALOG hive_catalog_azure
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls2.oauth2_client_id" = "<service_principal_client_id>",
    "azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
    "azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"
);

Broker Load

azure.adls2.oauth2_client_id、azure.adls2.oauth2_client_secret、azure.adls2.oauth2_client_endpoint、およびファイルパス (DATA INFILE) を LOAD LABEL ステートメントで次のように設定します。

LOAD LABEL mydatabase.label_gen2_principal
(
    DATA INFILE("abfs[s]://<container>@<storage_account>.dfs.core.windows.net/<path>/file1.parquet")
    INTO TABLE table1
    FORMAT AS "parquet"
)
WITH BROKER
(
    "azure.adls2.oauth2_client_id" = "<service_principal_client_id>",
    "azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
    "azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"
);

Data Lake Storage Gen1

注意

Microsoft は 2024 年 2 月 29 日に Azure Data Lake Storage Gen1 を廃止しました。このトピックの Gen1 に関するセクションは、参考のために残しています。

StarRocks は、Data Lake Storage Gen1 にアクセスするために次の認証方法のいずれかを使用することをサポートしています。

マネージドサービス ID
サービスプリンシパル

注意

Data Lake Storage Gen1 からデータをロードしたり、ファイルをクエリしたりする場合、データにアクセスするために adl プロトコルを使用し、ファイルパスを adl://<data_lake_storage_gen1_name>.azuredatalakestore.net/<path>/<file_name> として記述する必要があります。

マネージドサービス ID

パラメータ

パラメータ	説明
azure.adls1.use_managed_service_identity	マネージドサービス ID 認証方法を有効にするかどうかを指定します。値を `true` に設定します。

例

External catalog

azure.adls1.use_managed_service_identity を CREATE EXTERNAL CATALOG ステートメントで次のように設定します。

CREATE EXTERNAL CATALOG hive_catalog_azure
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls1.use_managed_service_identity" = "true"
);

Broker Load

azure.adls1.use_managed_service_identity およびファイルパス (DATA INFILE) を LOAD LABEL ステートメントで次のように設定します。

LOAD LABEL mydatabase.label_gen1_identity
(
    DATA INFILE("adl://<data_lake_storage_gen1_name>.azuredatalakestore.net/<path>/file1.parquet")
    INTO TABLE table1
    FORMAT AS "parquet"
)
WITH BROKER
(
    "azure.adls1.use_managed_service_identity" = "true"
);

サービスプリンシパル

サービスプリンシパルを作成し、そのアプリケーション (クライアント) ID、クライアントシークレット、および OAuth 2.0 トークンエンドポイント (v1) を取得する方法については、Data Lake Storage Gen2 > サービスプリンシパルを参照してください。

注記

サービスプリンシパルは、PhoenixAI クラスターのデプロイに使用されたものである必要があります。

パラメータ

パラメータ	説明
azure.adls1.oauth2_client_id	サービスプリンシパルのアプリケーション (クライアント) ID。
azure.adls1.oauth2_credential	サービスプリンシパルのクライアントシークレットの値。
azure.adls1.oauth2_endpoint	サービスプリンシパルの OAuth 2.0 トークンエンドポイント (v1)。

例

External catalog

azure.adls1.oauth2_client_id、azure.adls1.oauth2_credential、および azure.adls1.oauth2_endpoint を CREATE EXTERNAL CATALOG ステートメントで次のように設定します。

CREATE EXTERNAL CATALOG hive_catalog_azure
PROPERTIES
(
    "type" = "hive", 
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls1.oauth2_client_id" = "<service_principal_client_id>",
    "azure.adls1.oauth2_credential" = "<service_principal_client_secret>",
    "azure.adls1.oauth2_endpoint" = "<OAuth_2.0_token_endpoint_v1>"
);

Broker Load

azure.adls1.oauth2_client_id、azure.adls1.oauth2_credential、azure.adls1.oauth2_endpoint、およびファイルパス (DATA INFILE) を LOAD LABEL ステートメントで次のように設定します。

LOAD LABEL mydatabase.label_gen1_principal
(
    DATA INFILE("adl://<data_lake_storage_gen1_name>.azuredatalakestore.net/<path>/file1.parquet")
    INTO TABLE table1
    FORMAT AS "parquet"
)
WITH BROKER
(
    "azure.adls1.oauth2_client_id" = "<service_principal_client_id>",
    "azure.adls1.oauth2_credential" = "<service_principal_client_secret>",
    "azure.adls1.oauth2_endpoint" = "<OAuth_2.0_token_endpoint_v1>"
);

Blob Storage​

共有キー (ストレージアカウントのアクセスキー)​

パラメータ​

例​

External catalog​

Broker Load​

SAS トークン​

パラメータ​

例​

External catalog​

Broker Load​

Data Lake Storage Gen2​

マネージド ID​

準備​

パラメータ​

例​

External catalog​

Broker Load​

共有キー (ストレージアカウントのアクセスキー)​

パラメータ​

例​

External catalog​

Broker Load​

サービスプリンシパル​

準備​

パラメータ​

例​

External catalog​

Broker Load​

Data Lake Storage Gen1​

マネージドサービス ID​

パラメータ​

例​

External catalog​

Broker Load​

サービスプリンシパル​

パラメータ​

例​

External catalog​

Broker Load​

Blob Storage

共有キー (ストレージアカウントのアクセスキー)

パラメータ

例

External catalog

Broker Load

SAS トークン

パラメータ

例

External catalog

Broker Load

Data Lake Storage Gen2

マネージド ID

準備

パラメータ

例

External catalog

Broker Load

共有キー (ストレージアカウントのアクセスキー)

パラメータ

例

External catalog

Broker Load

サービスプリンシパル

準備

パラメータ

例

External catalog

Broker Load

Data Lake Storage Gen1

マネージドサービス ID

パラメータ

例

External catalog

Broker Load

サービスプリンシパル

パラメータ

例

External catalog

Broker Load