Tutorial: Aceitar e receber dados – Azure Data Share

Artigo
12/19/2023

Neste tutorial, você aprenderá a aceitar um convite de compartilhamento de dados usando o Azure Data Share. Você aprenderá a receber dados que estão sendo compartilhados e a habilitar um intervalo de atualização regular para garantir a presença do instantâneo mais recente dos dados que estão sendo compartilhados.

Como aceitar um convite do Azure Data Share
Criar um Azure Data Share
Especificar um destino para seus dados
Criar uma assinatura para seu compartilhamento de dados para a atualização agendada

Pré-requisitos

Para aceitar um convite de compartilhamento de dados, você precisa criar vários recursos do Azure, que estão listados abaixo.

Cumpra todos os pré-requisitos antes de aceitar um convite de compartilhamento de dados.

Assinatura do Azure: Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Um convite do Azure Data Share: Um convite do Microsoft Azure com o assunto intitulado "Convite do Azure Data Share de yourdataprovider@domain.com ".
Registre o provedor de recursos Microsoft.DataShare na assinatura do Azure, na qual você criará um recurso do Data Share e a assinatura do Azure em que os armazenamentos de dados do Azure de destino estão localizados.

Receber dados em uma conta de armazenamento

Uma conta de Armazenamento do Azure: Se você não tiver uma, poderá criar uma conta de Armazenamento do Azure.
Permissão para gravar na conta de armazenamento, que está presente em Microsoft.Storage/storageAccounts/write. Essa permissão existe na função Colaborador da Conta de Armazenamento.
Permissão para adicionar uma atribuição de função à conta de armazenamento, que está presente em Microsoft.Authorization/role assignments/write. Essa permissão existe na função Proprietário.

Receber dados em um destino baseado em SQL

Se você optar por receber os dados no Banco de Dados SQL do Azure e no Azure Synapse Analytics, veja abaixo a lista de pré-requisitos.

Pré-requisitos para o recebimento de dados no Banco de Dados SQL do Azure ou no Azure Synapse Analytics (antigo SQL DW do Azure)

Um Banco de Dados SQL do Azure ou o Azure Synapse Analytics (antigo SQL DW do Azure).
Permissão para gravar nos bancos de dados no SQL Server, que está presente em Microsoft.Sql/servers/databases/write. Essa permissão existe na função Colaborador.
Administrador do Microsoft Entra no SQL Server
Acesso ao firewall do SQL Server. Isso pode ser feito executando as seguintes etapas:
1. No SQL Server, no portal do Azure, navegue até Firewalls e redes virtuais
2. Escolha Sim na opção Permitir que serviços e recursos do Azure acessem este servidor.
3. Selecione +Adicionar IP de cliente. O endereço IP do cliente está sujeito a alterações. Esse processo talvez precise ser repetido na próxima vez em que você estiver compartilhando dados SQL do portal do Azure. Você também pode adicionar um intervalo de IP.
4. Selecione Salvar.

Pré-requisitos para o recebimento de dados no pool de SQL do Azure Synapse Analytics (workspace)

Um pool de SQL dedicado do Azure Synapse Analytics (workspace). No momento, não há suporte para o recebimento de dados no pool de SQL sem servidor.
Permissão de gravação no pool de SQL no workspace do Azure Synapse, que está presente em Microsoft.Synapse/workspaces/sqlPools/write. Essa permissão existe na função Colaborador.
Permissão para que a identidade gerenciada do recurso do Data Share acesse o pool de SQL do workspace do Azure Synapse. Isso pode ser feito executando as seguintes etapas:
1. No portal do Azure, navegue até o workspace do Azure Synapse. Selecione o administrador do Active Directory do SQL na navegação à esquerda e defina-se como o administrador do Microsoft Entra.
2. Abra o Synapse Studio e selecione Gerenciar no painel de navegação à esquerda. Escolha Controle de acesso em Segurança. Atribua a você mesmo a função Administrador do SQL ou Administrador do workspace.
3. No Synapse Studio, selecione Desenvolver no painel de navegação à esquerda. Execute o script a seguir no pool de SQL para adicionar a identidade gerenciada do recurso do Data Share como um 'db_datareader, db_datawriter, db_ddladmin'.
```
create user "<share_acc_name>" from external provider; 
exec sp_addrolemember db_datareader, "<share_acc_name>"; 
exec sp_addrolemember db_datawriter, "<share_acc_name>"; 
exec sp_addrolemember db_ddladmin, "<share_acc_name>";
```
  O <share_acc_name> é o nome do seu recurso do Data Share. Se você ainda não criou um recurso do Data Share, poderá voltar a esse pré-requisito mais tarde.
Acesso ao Firewall do workspace do Azure Synapse. Isso pode ser feito executando as seguintes etapas:
1. No portal do Azure, navegue até o workspace do Azure Synapse. Selecione Firewalls no painel de navegação à esquerda.
2. Selecione ATIVADO na opção Permitir que serviços e recursos do Azure acessem este workspace.
3. Selecione +Adicionar IP de cliente. O endereço IP do cliente está sujeito a alterações. Esse processo talvez precise ser repetido na próxima vez em que você estiver compartilhando dados SQL do portal do Azure. Você também pode adicionar um intervalo de IP.
4. Selecione Salvar.

Receba os dados em um cluster do Azure Data Explorer:

Um cluster do Azure Data Explorer no mesmo data center do Azure que o cluster do Data Explorer do provedor de dados: Se você não tiver, poderá criar um cluster do Azure Data Explorer. Se você não conhecer o data center do Azure do cluster do provedor de dados, poderá criá-lo posteriormente no processo.
Permissão para gravar no cluster do Azure Data Explorer, que está presente em Microsoft.Kusto/clusters/write. Essa permissão existe na função Colaborador.

Entre no portal do Azure.

Convite aberto

Você pode abrir o convite do email ou diretamente do portal do Azure.

Para abrir um convite do email, confira sua caixa de entrada para um convite de seu provedor de dados. O convite é do Microsoft Azure, intitulado Convite do Azure Data Share de yourdataprovider@domain.com . Selecione Exibir convite para ver seu convite no Azure.

Para abrir o convite diretamente do portal do Azure, pesquise por Convites do Data Share no portal do Azure. Essa ação levará você à lista de convites do Data Share.

Se você for um usuário convidado de um locatário, precisará confirmar seu endereço de email para o locatário antes de ver o convite do Data Share pela primeira vez. Depois de confirmado, ele será válido por 12 meses.
Selecione o convite que deseja ver.

Prepare seu ambiente da CLI do Azure e veja seus convites.

Comece preparando seu ambiente para a CLI do Azure:

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Execute o comando az datashare consumer-invitation list-invitation para ver seus convites atuais:

az datashare consumer consumer-invitation list-invitation

Copie sua ID de convite para uso na próxima seção.

Comece preparando seu ambiente para o PowerShell. Você pode executar comandos do PowerShell localmente ou usar o ambiente do Bash no Azure Cloud Shell.

Se você optar por usar o Azure PowerShell localmente:
- Instale a versão mais recente do módulo do Az PowerShell.
- Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
Se você optar por usar o Azure Cloud Shell:
- Confira Visão geral do Azure Cloud Shell para obter mais informações.

Use o comando Connect-AzAccount para se conectar à sua conta do Azure.
```
Connect-AzAccount
```
Execute o comando Set-AzContext para definir a assinatura correta, se você tiver várias assinaturas.
```
Set-AzContext [SubscriptionID/SubscriptionName]
```
Execute o comando Get-AzDataShareReceivedInvitation para ver seus convites atuais:
```
Get-AzDataShareReceivedInvitation
```

Copie sua ID de convite para uso na próxima seção.

Aceitar o convite

Examine todos os campos, incluindo os Termos de uso. Se você concordar com os termos de uso, será solicitado a marcar a caixa para indicar sua concordância.
Em Conta do Data Share de Destino, selecione a assinatura e o Grupo de Recursos em que você vai implantar seu Data Share.

Para o campo Conta do Data Share, selecione Criar nova se você não tiver uma conta do Data Share. Caso contrário, selecione uma conta do Data Share em que você gostaria de aceitar o compartilhamento de dados.

Para o campo Nome do Compartilhamento Recebido, deixe o padrão especificado pelo provedor de dados ou especifique um novo nome para o compartilhamento recebido.

Depois de concordar com os termos de uso e especificar uma conta do Data Share para gerenciar seu compartilhamento recebido, selecione Aceitar e configurar. Uma assinatura de compartilhamento será criada.

Essa ação levará você para o compartilhamento recebido na sua conta do Data Share.

Se você não quiser aceitar o convite, selecione Rejeitar.

Use o comando az datashare share-subscription create para criar o Data Share.

az datashare share-subscription create --resource-group share-rg \
  --name "fabrikamsolutions" --account-name FabrikamDataShareAccount \
  --invitation-id 89abcdef-0123-4567-89ab-cdef01234567 \
  --source-share-location "East US 2"

Use o comando New-AzDataShareSubscription para criar o Data Share. A InvitationId será a ID que você coletou na etapa anterior.

New-AzDataShareSubscription -ResourceGroupName <String> -AccountName <String> -Name <String> -InvitationId <String>

Siga as etapas abaixo para configurar o local em que deseja receber os dados.

Selecione a guia Conjuntos de Dados. Marque a caixa ao lado do conjunto de dados ao qual deseja atribuir um destino. Selecione + Mapear para o destino para escolher um armazenamento de dados de destino.
Selecione um tipo de armazenamento de dados de destino no qual deseja que os dados sejam inseridos. Todos os arquivos de dados ou tabelas no armazenamento de dados de destino com o mesmo caminho e nome serão substituídos. Se você estiver recebendo dados no Banco de Dados SQL do Azure ou no Azure Synapse Analytics (antigo SQL DW do Azure), marque a caixa de seleção Permitir que o Data Share execute o script 'create user' acima em meu nome.

Para o compartilhamento in-loco, selecione um armazenamento de dados na Localização especificada. A Localização é o data center do Azure no qual o armazenamento de dados de origem do provedor de dados está localizado. Depois que o conjunto de dados for mapeado, siga o link no Caminho de Destino para acessar os dados.
Para o compartilhamento baseado em instantâneo, se o provedor de dados tiver criado um agendamento de instantâneo para fornecer atualização regular aos dados, você também poderá habilitar o agendamento de instantâneo selecionando a guia Agendamento de Instantâneos. Marque a caixa ao lado do agendamento de instantâneo e selecione + Habilitar. O primeiro instantâneo agendado começará dentro de um minuto após a hora agendada e os instantâneos posteriores começarão em segundos da hora agendada.

Os metadados dos arquivos copiados não são persistidos após cada execução. Isso ocorre por design.

Use estes comandos para configurar a localização em que deseja receber os dados.

Execute o comando az datashare consumer-source-data-set list para obter a ID do conjunto de dados:

az datashare consumer-source-data-set list --resource-group "share-rg" \
 --account-name "FabrikamDataShareAccount" \
   --share-subscription-name "fabrikamsolutions" \

Execute o comando az storage account create para criar uma conta de armazenamento para este Data Share:
```
az storage account create --resource-group "share-rg" --name "FabrikamDataShareStorageAccount" \
```

Use o comando az storage account show para obter a ID da conta de armazenamento:

az storage account show --resource-group "share-rg" --name "FabrikamDataShareStorageAccount" \
 --query "id"

Use o seguinte comando para obter a ID da entidade de segurança da conta:

az datashare account show --resource-group "share-rg" --name "FabrikamDataShareAccount" \
  --query "identity.principalId"

Use o comando az role assignment create para criar uma atribuição de função à entidade de segurança da conta usando a ID da entidade de segurança da conta e a ID da conta de armazenamento:

az role assignment create --role "Contributor" \
  --assignee-object-id 6789abcd-ef01-2345-6789-abcdef012345 
  --assignee-principal-type ServicePrincipal --scope "your\storage\account\id\path"

Crie uma variável para o mapeamento com base na ID do conjunto de dados da etapa 1:

$mapping='{\"data_set_id\":\"' + $dataset_id + '\",\"container_name\":\"newcontainer\",
  \"storage_account_name\":\"datashareconsumersa\",\"kind\":\"BlobFolder\",\"prefix\":\"consumer\"}'

Use o comando az datashare data-set-mapping create para criar o mapeamento do conjunto de dados:

az datashare data-set-mapping create --account-name "FabrikamDataShareAccount" \
 --data-set-mapping-name "datasetmapping" --resource-group "share-rg" \
 --share-subscription-name "fabrikamsolutions" --blob-folder-data-set-mapping $mapping

Execute o comando az datashare share-subscription synchronize para iniciar a sincronização do conjunto de dados.

az datashare share-subscription synchronize \
  --resource-group "share-rg" --account-name "FabrikamDataShareAccount"  \
  --name "Fabrikam Solutions" --synchronization-mode "Incremental" \

Execute o comando az datashare share-subscription list-synchronization para ver uma lista das sincronizações:

az datashare share-subscription list-synchronization \
  --resource-group "share-rg" --account-name "FabrikamDataShareAccount" \
  --share-subscription-name "Fabrikam Solutions" \

Use o comando az datashare share-subscription list-source-share-synchronization-setting para ver as configurações de sincronização definidas no compartilhamento.

az datashare share-subscription list-source-share-synchronization-setting \
  --resource-group "share-rg" --account-name "FabrikamDataShareAccount" \
  --share-subscription-name "Fabrikam Solutions"

Use estes comandos para configurar a localização em que deseja receber os dados.

Execute o comando Get-AzDataShareSourceDataSet para obter a ID do conjunto de dados:

Get-AzDataShareSourceDataSet -ResourceGroupName <String> -AccountName <String> -ShareSubscriptionName <String>

Se você ainda não tiver um local para armazenar os dados compartilhados, siga estas etapas para criar uma conta de armazenamento. Se você já tiver um armazenamento, pule para as próximas etapas.
1. Execute o comando New-AzStorageAccount para criar uma conta do Armazenamento Azure:
```
$storageAccount = New-AzStorageAccount -ResourceGroupName <String> -AccountName <String> -Location <String> -SkuName <String>

$ctx = $storageAccount.Context
```
2. Execute o comando New-AzStorageContainer para criar um contêiner em sua nova conta do Armazenamento do Azure que conterá seus dados:
```
$containerName = <String>

New-AzStorageContainer -Name $containerName -Context $ctx -Permission blob
```
3. Execute o comando Set-AzStorageBlobContent para carregar um arquivo. O exemplo a seguir carrega textfile.csv da pasta D:\testFiles na memória local para o contêiner que você criou.
```
Set-AzStorageBlobContent -File "D:\testFiles\textfile.csv" -Container $containerName -Blob "textfile.csv" -Context $ctx
```
Para obter mais informações sobre como trabalhar com o Armazenamento do Azure no PowerShell, siga este guia do PowerShell do Armazenamento do Azure.
Use o comando Get-AzStorageAccount para obter a ID da conta de armazenamento:
```
Get-AzStorageAccount -ResourceGroupName <String> -Name <String>
```

Use a ID do conjunto de dados da primeira etapa e, em seguida, execute o comando New-AzDataShareDataSetMapping para criar o mapeamento do conjunto de dados:

New-AzDataShareDataSetMapping -ResourceGroupName <String> -AccountName <String> -ShareSubscriptionName <String> -Name <String> -StorageAccountResourceId <String> -DataSetId <String> -Container <String>

Execute o comando Start-AzDataShareSubscriptionSynchronization para iniciar a sincronização do conjunto de dados.

Start-AzDataShareSubscriptionSynchronization -ResourceGroupName <String> -AccountName <String> -ShareSubscriptionName <String> -SynchronizationMode <String>

Execute o comando Get-AzDataShareSubscriptionSynchronization para ver uma lista das suas sincronizações:

Get-AzDataShareSubscriptionSynchronization -ResourceGroupName <String> -AccountName <String> -ShareSubscriptionName <String>

Use o comando Get-AzDataShareSubscriptionSynchronizationDetail para ver as configurações de sincronização definidas no seu compartilhamento.

Get-AzDataShareSubscriptionSynchronizationDetail -ResourceGroupName <String> -AccountName <String> -ShareSubscriptionName <String> -SynchronizationId <String>

Disparar um instantâneo

Essas etapas se aplicam somente ao compartilhamento baseado em instantâneo.

Você pode disparar um instantâneo selecionando a guia Detalhes seguido de Disparar instantâneo. Aqui, você pode disparar um instantâneo completo ou incremental de seus dados. Se esta for a primeira vez que você está recebendo dados de seu provedor de dados, selecione a cópia completa.
Quando o status da última execução for bem-sucedido, acesse o armazenamento de dados de destino para exibir os dados recebidos. Selecione Conjuntos de dados e clique no link no Caminho de Destino.

Execute o comando az datashare trigger create para disparar um instantâneo:

az datashare trigger create --account-name "FabrikamDataShareAccount" --resource-group "share-rg" --share-subscription-name "Fabrikam Solutions" --scheduled-trigger recurrence-interval="Day" synchronization-mode="Incremental" synchronization-time="2018-11-14T04:47:52.9614956Z" --name "Trigger1"

Essas etapas se aplicam somente ao compartilhamento baseado em instantâneo.

Execute o comando New-AzDataShareTrigger para disparar um instantâneo:

New-AzDataShareTrigger -ResourceGroupName <String> -AccountName <String> -Name <String> -RecurrenceInterval <String> -SynchronizationTime <DateTime>

Exibir histórico

Esta etapa só se aplica ao compartilhamento baseado em instantâneo. Para ver o histórico dos seus instantâneos, selecione a guia Histórico. Aqui, você encontrará o histórico de todos os instantâneos gerados nos últimos 30 dias.

Limpar os recursos

Quando o recurso não for mais necessário, acesse a página Visão Geral do Data Share e selecione Excluir para removê-lo.

Próximas etapas

Neste tutorial, você aprendeu a aceitar e receber um Azure Data Share. Para saber mais sobre os conceitos do Azure Data Share, prossiga para a Terminologia do Azure Data Share.

Conceitos do Azure Data Share

Tutorial: Aceitar e receber dados usando o Azure Data Share