Configurar uma integração de catálogo para REST OneLake¶

Pré-requisitos¶

• Antes de começar, você deve encontrar o ID do seu espaço de trabalho no Fabric e o ID do item de dados para seu lakehouse no Fabric. Você especifica o ID do seu espaço de trabalho e o ID do item de dados posteriormente, ao criar uma integração de catálogo para REST OneLake.

  • Para encontrar o ID do seu espaço de trabalho (<workspaceID>), consulte o URL do site do Fabric para um item em um espaço de trabalho. Para obter mais informações, consulte Identificar o ID do seu espaço de trabalho na documentação do Microsoft Fabric. Copie o ID do seu espaço de trabalho para um editor de texto.

  • Para encontrar o ID do seu item de dados (``<dataItemID>), abra sua casa no lago e consulte o valor após «lakehouses» no URL. Para obter mais informações, consulte Configuração da fonte do lakehouse na documentação do Microsoft Fabric e consulte o item Connection. Copie o ID do seu item de dados para um editor de texto.

• No espaço de trabalho do Fabric, certifique-se de ter tabelas Iceberg em qualquer item de dados, como em um lakehouse.

Etapa 1: Configurar as permissões de acesso para o OneLake¶

Para configurar as permissões de acesso para o OneLake, você cria um registro de aplicativo no Microsoft Azure, adiciona a permissão user_impersonation ao seu registro de aplicativo e cria um novo segredo do cliente para o seu registro.

1. No Azure, crie um registro de aplicativo.

   Para obter detalhes, consulte Registrar um aplicativo no Microsoft Entra ID na documentação do Microsoft Entra.

2. No registro do seu aplicativo, adicione a permissão user_impersonation.

   Para começar, siga as quatro primeiras etapas em Usar o centro de administração do Microsoft Entra para encontrar as APIs que sua organização usa na documentação do Microsoft Graph.

   Importante

   Não alterne para a guia APIs my organization uses conforme descrito nas etapas. Em vez disso, alterne para a guia Microsoft APIs, selecione Azure Storage e adicione a permissão user_impersonation.

3. Crie um novo segredo do cliente para o registro do seu aplicativo e copie o segredo para um editor de texto.

   Para obter instruções, consulte Criar um novo segredo do cliente na documentação do Microsoft Entra. Você especifica esse segredo ao criar uma integração de catálogo.

   Importante

   Lembre-se de copiar o segredo para um editor de texto, pois não será possível recuperá-lo posteriormente.

4. Na página Overview do registro do seu aplicativo, copie Display name, Application (client) ID e Directory (tenant) ID para um editor de texto.

   Você especifica esses valores ao criar uma integração de catálogo e um volume externo.

Etapa 2: Conceder ao registro do seu aplicativo acesso ao seu espaço de trabalho do Fabric¶

Nesta etapa, você concede ao registro do seu aplicativo acesso ao seu espaço de trabalho no Fabric.

1. Navegue até o Microsoft Fabric e faça login.

2. Abra o espaço de trabalho do Microsoft Fabric.

3. Selecione Manage access.

4. Selecione + Add people or groups.

5. No campo Enter name or email, cole o nome do registro do seu aplicativo.

   Este nome é o Display name que você copiou quando configurou as permissões de acesso para o OneLake.

6. No menu suspenso, selecione acesso Contributor ou superior para permitir que o app crie o item do Fabric necessário.

7. Selecione Add.

Etapa 3: Criar uma integração de catálogo no Snowflake¶

Crie uma integração de catálogo para o ponto de extremidade da REST API usando o comando CREATE CATALOG INTEGRATION (Apache Iceberg™ REST).

Por exemplo:

CREATE OR REPLACE CATALOG INTEGRATION my_onelake_catalog_int
   CATALOG_SOURCE = ICEBERG_REST
   TABLE_FORMAT = ICEBERG
   REST_CONFIG = (
      CATALOG_URI = 'https://onelake.table.fabric.microsoft.com/iceberg'
      CATALOG_NAME = '<fabric_data_item_scope>'
   )
   REST_AUTHENTICATION = (
      TYPE = OAUTH
      OAUTH_TOKEN_URI = '<azure_active_directory_token_endpoint>'
      OAUTH_CLIENT_ID = '<entra_application_client_id>'
      OAUTH_CLIENT_SECRET = '<entra_application_client_secret>'
      OAUTH_ALLOWED_SCOPES = ('https://storage.azure.com/.default')
   )
   ENABLED = TRUE;

Onde:

• https://onelake.table.fabric.microsoft.com/iceberg é o URL base no ponto de extremidade da tabela do OneLake.

• <fabric_data_item_scope> is the Fabric data item scope, in the form <workspaceID>/<dataItemID>, such as 12345678-abcd-1abc-1a11-111111ab1111/11111111-abcd-1111-1ab1-1111a1a1ab91. To find your <workspaceID> and <dataItemID>, consulte Pré-requisitos.

• <azure_active_directory_token_endpoint_> is your Azure Active Directory OAuth 2.0 token endpoint URL, in the form of https://login.microsoftonline.com/<entra_tenant_id>/oauth2/v2.0/token. For <entra_tenant_id>, você especifica o ID do seu locatário Entra, que você copiou quando configurou as permissões de acesso para o OneLake.

• <entra_application_client_id> é o ID do seu cliente de aplicativo Entra, que você copiou quando configurou as permissões de acesso para o OneLake, como 11111111-aabb-1a11-abc1-ab11111a11a1.

• <entra_application_client_secret> é o segredo do cliente do aplicativo, que você copiou quando configurou as permissões de acesso para o OneLake.

• https://storage.azure.com/.default é o público-alvo do token de armazenamento.

Etapa 4: Configuração de um volume externo¶

Nesta etapa, você configura um volume externo para o Azure com o URL do Azure OneLake e o ID do locatário Entra.

1. Crie um volume externo usando o comando CREATE EXTERNAL VOLUME.

   Por exemplo:

   CREATE OR REPLACE EXTERNAL VOLUME my_onelake_extvol
      STORAGE_LOCATIONS =
      (
         (
               NAME = 'my_onelake_extvol'
               STORAGE_PROVIDER = 'AZURE'
               STORAGE_BASE_URL = '<azure_onelake_url>'
               AZURE_TENANT_ID='<entra_tenant_id>'
         )
      )
      ALLOW_WRITES = FALSE;
   

   Copy

   Onde:

   • <azure_onelake_url> is your Azure OneLake URL, in the form of azure://onelake.dfs.fabric.microsoft.com/<workspaceID>/<dataItemID>, such as azure://onelake.dfs.fabric.microsoft.com/12345678-abcd-1abc-1a11-111111ab1111/11111111-abcd-1111-1ab1-1111a1a1ab91. To find your <workspaceID> and <dataItemID>, consulte Pré-requisitos.

   • <entra_tenant_id> is your Entra tenant ID, such as, 11111111-aabb-1a11-abc1-ab11111a11a1. Você copiou o ID do seu locatário Entra quando configurou as permissões de acesso para o OneLake.

2. Para recuperar um URL para a página de solicitação de permissões da Microsoft, use o comando DESCRIBE EXTERNAL VOLUME. Especifique o nome do volume externo criado anteriormente.

   DESC EXTERNAL VOLUME my_onelake_extvol;
   

   Copy

   Registre os valores para as seguintes propriedades:

   Propriedade	Descrição
   AZURE_CONSENT_URL	URL para a página de solicitação de permissões da Microsoft.
   AZURE_MULTI_TENANT_APP_NAME	Nome do aplicativo cliente do Snowflake criado para sua conta. Em uma etapa posterior desta seção, você concede a este aplicativo a permissão para obter um token de acesso em seus locais de armazenamento permitidos.

   Você usa esses valores nas etapas a seguir.

3. Em um navegador da Web, navegue até a página de solicitação de permissões da Microsoft (o AZURE_CONSENT_URL).

4. Selecione Accept. Essa ação permite que a entidade do serviço Azure criada para sua conta Snowflake obtenha um token de acesso a um recurso especificado dentro de seu locatário. A obtenção de um token de acesso só tem sucesso se você conceder à entidade de serviço as permissões apropriadas no nível da conta de armazenamento (consulte a próxima etapa).

5. Conceda permissão ao aplicativo multilocatário para obter um token de acesso em seu local de armazenamento permitido no Fabric.

   1. Navegue até o Microsoft Fabric e faça login.

   2. Abra o espaço de trabalho do Microsoft Fabric.

   3. Selecione Manage access.

   4. Selecione + Add people or groups.

   5. No campo Enter name or email, cole o valor que você registrou para AZURE_MULTI_TENANT_APP_NAME.

   6. No menu suspenso, selecione acesso Contributor ou superior para permitir que o app crie o item do Fabric necessário.

   7. Selecione Add.

Para obter mais informações, consulte Exemplo de código de integração de catálogo e volume externo do Snowflake para o ponto de extremidade REST no Microsoft Fabric na documentação do Microsoft Fabric.

Próximos passos¶

Depois de configurar uma integração de catálogo para a REST do OneLake e um volume externo, você pode usar o comando CREATE DATABASE (vinculado a catálogo) para criar um banco de dados vinculado a catálogo e, em seguida, ler suas tabelas do OneLake no Snowflake.

Ao criar seu banco de dados vinculado a catálogo, você especifica a integração do catálogo e o volume externo que criou.

Por exemplo:

CREATE OR REPLACE DATABASE my_linked_db
   LINKED_CATALOG = (
      CATALOG = 'my_onelake_catalog_int'
   )
   EXTERNAL_VOLUME = 'my_onelake_extvol';

SELECT SYSTEM$CATALOG_LINK_STATUS('IRC_CATALOG_LINKED');

SELECT * FROM my_linked_db."dbo"."sentiment";