Registro de uma conexão de serviço¶

Este tópico aborda como registrar suas credenciais de conexão de serviço com o Snowflake ou seu serviço de terceiros (por exemplo, Apache Spark™). O administrador do Snowflake Open Catalog registra uma conexão de serviço.

O código de exemplo neste tópico mostra como registrar uma conexão de serviço no Spark, e o código de exemplo está em PySpark.

Pré-requisitos¶

Antes de registrar uma conexão de serviço, você precisa configurar uma conexão de serviço. Para obter instruções, consulte Configuração de uma conexão de serviço.

Registro de uma conexão de serviço¶

O código de exemplo a seguir é para registrar uma única conexão de serviço.

Observação

Você também pode registrar várias conexões de serviço. Consulte Exemplo 2: registro de duas conexões de serviço.

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.
`<client_id>`	Especifica o ID do cliente que a entidade de serviço deve usar. Insira o ID do cliente que você copiou quando configurou uma nova conexão de serviço.
`<client_secret>`	Especifica o segredo de cliente que a entidade de serviço deve usar. Insira o segredo que você copiou quando configurou uma nova conexão de serviço.
`<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.
`<principal_role_name>`	Especifica a função de entidade concedida à entidade de serviço. Para visualizar essa função de entidade, no Open Catalog, selecione a página Connections, selecione sua conexão de serviço e, na caixa de diálogo Principal Details, consulte Principal Roles.

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.credential','<client_id>:<client_secret>') \
    .config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
    .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
    .getOrCreate()

Registro de uma conexão de serviço entre regiões (somente Amazon S3)¶

O código de exemplo a seguir é para registrar uma conexão de serviço 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.credential','<client_id>:<client_secret>') \
    .config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
    .config('spark.sql.catalog.opencatalog.client.region','<target_s3_region>') \
    .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
    .getOrCreate()

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.
`<client_id>`	Especifica o ID do cliente que a entidade de serviço deve usar.
`<client_secret>`	Especifica o segredo de cliente que a entidade de serviço deve usar.
`<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.
`<principal_role_name>`	Especifica a função de entidade concedida à entidade de serviço.

Exemplos¶

Esta seção contém exemplos de registro de uma conexão de serviço no Spark.

Exemplo 1: registro de uma única conexão de serviço (S3)
Exemplo 2: registro de duas conexões de serviço (S3)
Exemplo 3: registro de uma única conexão de serviço (Cloud Storage from Google)
Exemplo 4: registro de uma única conexão de serviço (Azure)

Exemplo 1: Registro de uma única conexão de serviço (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.credential','000000000000000000000000000=:1111111111111111111111111111111111111111111=') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:data_engineer') \
    .getOrCreate()

Exemplo 2: Registro de duas conexões de serviço (S3)¶

Importante

Ao registrar várias conexões de serviço, é necessário alterar as instâncias do opencatalog no código da primeira conexão para um texto exclusivo no código de cada conexão subsequente. Por exemplo, no código a seguir, as instâncias opencatalog para a primeira conexão são alteradas para opencatalog1 para a segunda conexão:

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.credential','000000000000000000000000000=:1111111111111111111111111111111111111111111=') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:data_scientist') \
    .config('spark.sql.catalog.opencatalog1', 'org.apache.iceberg.spark.SparkCatalog') \
    .config('spark.sql.catalog.opencatalog1.type', 'rest') \
    .config('spark.sql.catalog.opencatalog1.uri','https://ab12345.snowflakecomputing.com/polaris/api/catalog') \
    .config('spark.sql.catalog.opencatalog1.header.X-Iceberg-Access-Delegation','vended-credentials') \
    .config('spark.sql.catalog.opencatalog1.credential','222222222222222222222222222=:3333333333333333333333333333333333333333333=') \
    .config('spark.sql.catalog.opencatalog1.warehouse','Catalog2') \
    .config('spark.sql.catalog.opencatalog1.scope','PRINCIPAL_ROLE:data_scientist') \
    .getOrCreate()

Exemplo 3: Registro de uma única conexão de serviço (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.credential','000000000000000000000000000=:1111111111111111111111111111111111111111111=') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:data_engineer') \
    .getOrCreate()

Exemplo 4: registro de uma única conexão de serviço (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.credential','000000000000000000000000000=:1111111111111111111111111111111111111111111=') \
    .config('spark.sql.catalog.opencatalog.warehouse','Catalog1') \
    .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:data_engineer') \
    .getOrCreate()

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.