Conexão ao Snowflake Open Catalog com OAuth externo¶

Este tópico descreve como se conectar ao Snowflake Open Catalog com OAuth externo usando um aplicativo do cliente.

O código de exemplo neste tópico mostra como se conectar usando o Apache Spark™, e o código de exemplo está em PySpark.

Nota

Se estiver usando o Snowflake para consulta tabelas gerenciadas Open Catalog, é possível criar uma integração de catálogo para o Snowflake que usa o OAuth externo. Para obter mais informações, consulte CREATE CATALOG INTEGRATION (Snowflake Open Catalog) na documentação do Snowflake.

Pré-requisitos¶

Antes de se conectar ao Open Catalog com OAuth externo, você precisa configurar o OAuth externo no Open Catalog. Para obter instruções, consulte Configuração de OAuth externo no Snowflake Open Catalog.

Conecte-se ao Open Catalog usando o token de atualização automática (método preferido)¶

Use este método para se conectar usando um token de atualização automática para que você não precise atualizar o token manualmente.

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,<maven_coordinate>') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
    .config('spark.sql.catalog.opencatalog.rest.auth.type','oauth2') \
    .config('spark.sql.catalog.opencatalog.oauth2-server-uri','<oauth2_server_uri>') \
    .config('spark.sql.catalog.opencatalog.credential','<oauth_client_id>:<oauth_client_secret>') \
    .config('spark.sql.catalog.opencatalog.scope','SESSION:ROLE:<custom_role>') \
    .config('spark.sql.catalog.opencatalog.audience','https://<open_catalog_account_identifier>.snowflakecomputing.com') \
    .getOrCreate()

Copy

Parâmetros¶

Parâmetro	Descrição
`<catalog_name>`	Especifica o nome do catálogo ao qual se conectar. Importante: <catalog_name> diferencia maiúsculas de minúsculas.
`<maven_coordinate>`	Especifica a coordenada Maven para seu provedor de armazenamento em nuvem externo: S3: software.amazon.awssdk:bundle:2.20.160 Cloud Storage (do Google): org.apache.iceberg:iceberg-gcp-bundle:1.5.2 Azure: org.apache.iceberg:iceberg-azure-bundle:1.5.2 Se esse parâmetro não for exibido, o valor correto já foi especificado na amostra de código.
`<open_catalog_account_identifier>`	Especifica o identificador de conta da conta do Open Catalog. Dependendo da região e da plataforma de nuvem da conta, esse identificador pode ser o próprio localizador da conta (por exemplo, `xy12345`) ou incluir segmentos adicionais. Para obter mais informações, consulte Como usar um localizador de conta como um identificador.
`<oauth2_server_uri>`	URI do seu servidor OAuth2.
`<oauth_client_id>`	Seu ID de cliente OAuth2.
`<oauth_client_secret>`	Seu segredo de cliente OAuth2.
`<custom_role>`	O nome da função personalizada no Open Catalog cujos privilégios você deseja conceder à entidade de serviço.

Conecte-se ao Open Catalog usando um token de acesso¶

Se necessário, você pode se conectar ao Open Catalog usando um token de acesso. No entanto, o token de acesso expirará e você precisará atualizá-lo manualmente. Como alternativa, você pode conectar usando um token de atualização automática.

O código de exemplo a seguir é para conexão com o Open Catalog usando o Spark.

Parâmetros¶

Parâmetro	Descrição
`<catalog_name>`	Especifica o nome do catálogo ao qual se conectar. Importante: <catalog_name> diferencia maiúsculas de minúsculas.
`<maven_coordinate>`	Especifica a coordenada Maven para seu provedor de armazenamento em nuvem externo: S3: software.amazon.awssdk:bundle:2.20.160 Cloud Storage (do Google): org.apache.iceberg:iceberg-gcp-bundle:1.5.2 Azure: org.apache.iceberg:iceberg-azure-bundle:1.5.2 Se esse parâmetro não for exibido, o valor correto já foi especificado na amostra de código.
`<access_token>`	Especifica o token de acesso para o aplicativo do cliente a ser utilizado. Insira o token de acesso que você gerou ao configurar o OAuth externo no Open Catalog.
`<open_catalog_account_identifier>`	Especifica o identificador de conta da conta do Open Catalog. Dependendo da região e da plataforma de nuvem da conta, esse identificador pode ser o próprio localizador da conta (por exemplo, `xy12345`) ou incluir segmentos adicionais. Para obter mais informações, consulte Como usar um localizador de conta como um identificador.

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,<maven_coordinate>') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.token','<access_token>') \
    .config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
    .getOrCreate()

Copy

Conexão entre regiões (somente Amazon S3)¶

O código de exemplo a seguir é para conexão com o Open Catalog quando o seguinte for verdadeiro:

Sua conta do Open Catalog está hospedada no Amazon S3.
Seu provedor de armazenamento externo é o Amazon S3.
Sua conta do Open Catalog está hospedada em uma região S3 diferente da região S3 onde o bucket de armazenamento que contém suas tabelas do Apache Iceberg™ está localizado.

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.token','<access_token>') \
    .config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
    .config('spark.sql.catalog.opencatalog.client.region','<target_s3_region>') \
    .getOrCreate()

Copy

Parâmetros¶

Parâmetro	Descrição
`<catalog_name>`	Especifica o nome do catálogo ao qual se conectar. Importante: <catalog_name> diferencia maiúsculas de minúsculas.
`<access_token>`	Especifica o token de acesso para o aplicativo do cliente a ser utilizado. Insira o token de acesso que você gerou ao configurar o OAuth externo no Open Catalog.
`<open_catalog_account_identifier>`	Especifica o identificador de conta da conta do Open Catalog. Dependendo da região e da plataforma de nuvem da conta, esse identificador pode ser o localizador da conta por si só (por exemplo, `xy12345`) ou incluir segmentos adicionais. Para obter mais informações, consulte Como usar um localizador de conta como um identificador.
`<target_s3_region>`	Especifica o código da região onde o bucket S3 que contém suas tabelas do Apache Iceberg está localizado. Para os códigos de região, veja pontos de extremidade do servidor AWS e consulte a coluna Região na tabela.

Exemplos¶

Esta seção contém exemplos de conexão com o Open Catalog usando o Spark:

Exemplo 1: conectar (S3)¶

Consulte:

Conexão usando atualização automática (S3)
Conexão usando o token de acesso (S3)

Conexão usando atualização automática (S3)¶

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://ab12345.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .config('spark.sql.catalog.opencatalog.rest.auth.type','oauth2') \
    .config('spark.sql.catalog.opencatalog.oauth2-server-uri','your-tenant.region.auth0.com') \
    .config('spark.sql.catalog.opencatalog.credential','11111111111111111111111111111111:222222222222222222222222222222222222222222222222222222222222222222') \
    .config('spark.sql.catalog.opencatalog.scope','SESSION:ROLE:DATA_ENG') \
    .config('spark.sql.catalog.opencatalog.audience','https://ab12345.snowflakecomputing.com') \
    .getOrCreate()

Copy

Conexão usando o token de acesso (S3)¶

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://ab12345.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.token','0000000000000000000000000001111111111111111111111111111111111111111111') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .getOrCreate()

Copy

Exemplo 2: conectar (Cloud Storage do Google)¶

Consulte:

Conexão-se usando a atualização automática (Cloud Storage do Google)
Conexão usando o token de acesso (Cloud Storage do Google)

Conexão usando atualização automática (Cloud Storage do Google)¶

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,org.apache.iceberg:iceberg-gcp-bundle:1.5.2') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://ab12345.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .config('spark.sql.catalog.opencatalog.rest.auth.type','oauth2') \
    .config('spark.sql.catalog.opencatalog.oauth2-server-uri','your-tenant.region.auth0.com') \
    .config('spark.sql.catalog.opencatalog.credential','11111111111111111111111111111111:222222222222222222222222222222222222222222222222222222222222222222') \
    .config('spark.sql.catalog.opencatalog.scope','SESSION:ROLE:DATA_ENG') \
    .config('spark.sql.catalog.opencatalog.audience','https://ab12345.snowflakecomputing.com') \
    .getOrCreate()

Copy

Conexão usando o token de acesso (Cloud Storage do Google)¶

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,org.apache.iceberg:iceberg-gcp-bundle:1.5.2') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://ab12345.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.token','0000000000000000000000000001111111111111111111111111111111111111111111') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .getOrCreate()

Copy

Exemplo 3: conectar (Azure)¶

Consulte:

Conexão usando a atualização automática do (Azure)
Conexão usando o token de acesso (Azure)

Conexão usando atualização automática (Azure)¶

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,org.apache.iceberg:iceberg-azure-bundle:1.5.2') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://ab12345.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .config('spark.sql.catalog.opencatalog.rest.auth.type','oauth2') \
    .config('spark.sql.catalog.opencatalog.oauth2-server-uri','your-tenant.region.auth0.com') \
    .config('spark.sql.catalog.opencatalog.credential','11111111111111111111111111111111:222222222222222222222222222222222222222222222222222222222222222222') \
    .config('spark.sql.catalog.opencatalog.scope','SESSION:ROLE:DATA_ENG') \
    .config('spark.sql.catalog.opencatalog.audience','https://ab12345.snowflakecomputing.com') \
    .getOrCreate()

Copy

Conexão usando token de acesso (Azure)¶

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
    .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,org.apache.iceberg:iceberg-azure-bundle:1.5.2') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .config('spark.sql.defaultCatalog', 'opencatalog') \
    .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog.type', 'rest') \
    .config('spark.sql.catalog.opencatalog.uri','https://ab12345.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog.token','0000000000000000000000000001111111111111111111111111111111111111111111') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .getOrCreate()

Copy

Verifique a conexão com o Open Catalog¶

Para verificar se o Spark está conectado ao Open Catalog, liste os namespaces do catálogo. Para obter mais informações, consulte Listar namespaces.