Criar uma SAS (assinatura de acesso compartilhado) do OneLake (versão prévia)

Artigo
12/03/2024

Crie uma SAS do OneLake para fornecer acesso delegado de curto prazo a uma pasta ou arquivo no OneLake com suporte de suas credenciais do Microsoft Entra. A SAS do OneLake pode fornecer acesso temporário a aplicativos sem suporte para o Microsoft Entra, permitindo que eles carreguem dados ou sirvam como proxies entre outros aplicativos de clientes ou ISVs (Fornecedores Independentes de Software).

Para criar uma SAS do OneLake, primeiro solicite uma chave de delegação de usuário, que você usa para assinar a SAS. Para solicitar uma chave de delegação de usuário, chame a operação Obter Chave de Delegação do Usuário. A SAS do OneLake pode conceder acesso a arquivos e pastas somente em itens de dados e não pode ser usada para operações de gerenciamento, como criar ou excluir itens ou espaços de trabalho.

Uma SAS do OneLake pode conceder acesso a arquivos e pastas somente em itens de dados e não pode ser usada para operações de gerenciamento, como a criação de espaços de trabalho ou itens.

Uma SAS do OneLake é criada de forma semelhante à SAS delegada pelo usuário do Armazenamento do Microsoft Azure, usando os mesmos parâmetros para compatibilidade com ferramentas e aplicativos compatíveis com o Armazenamento do Microsoft Azure.

Importante

Esse recurso está na versão prévia.

Atribuir permissões

Solicitar uma chave de delegação de usuário é uma operação no nível do locatário no Fabric. Para solicitar uma chave de delegação de usuário, o usuário ou o princípio de segurança que solicita a chave de delegação do usuário deve ter pelo menos permissões de leitura em um espaço de trabalho no locatário do Fabric. A identidade do usuário solicitante é usada para autenticar a SAS, o que significa que o usuário deve ter permissão para os dados aos quais concede acesso à SAS.

Adquirir um token OAuth 2.0

Para obter a chave de delegação do usuário, primeiro solicite um token OAuth 2.0 do Microsoft Entra ID. Autorize a chamada para a operação Obter Chave de Delegação de Usuário fornecendo o token com o esquema de Portador. Para obter mais informações sobre como solicitar um token OAuth do Microsoft Entra ID, consulte Fluxos de autenticação e cenários de aplicativo.

Solicitar a chave de delegação do usuário

Chamar a operação Obter Chave de Delegação de Usuário retorna a chave como um conjunto de valores que são usados como parâmetros no token da SAS de delegação do usuário. Esses parâmetros são descritos na referência Obter Chave de Delegação do Usuário e na próxima seção.

Quando um cliente solicita uma chave para delegação de usuários usando um token OAuth 2.0, o OneLake retorna uma chave para delegação de usuários em nome do cliente. Uma SAS criada com essa chave de delegação de usuário é concedida, no máximo, às permissões concedidas ao cliente, com escopo reduzido às permissões explicitamente concedidas na SAS.

Você poderá criar qualquer número de SASs do OneLake para o tempo de vida da chave de delegação do usuário. No entanto, uma SAS do OneLake e chaves de delegação de usuário podem ser válidas por no máximo uma hora e não podem exceder o tempo de vida do token que as solicita. Essas restrições de tempo de vida são menores do que o tempo de vida máximo de uma SAS delegada pelo usuário do Armazenamento do Microsoft Azure.

Construir uma SAS de delegação de usuário

A tabela a seguir resume os campos com suporte para um token da SAS do OneLake. As seções subsequentes fornecem mais detalhes sobre esses parâmetros e como eles diferem dos tokens da SAS do Armazenamento do Microsoft Azure. O OneLake não dá suporte a todos os parâmetros opcionais com suporte pelo Armazenamento do Microsoft Azure, e uma SAS do OneLake construída com um parâmetro sem suporte será rejeitada.

Nome do campo da SAS	Parâmetro do token da SAS	Status	Descrição
`signedVersion`	`sv`	Obrigatório	Indica a versão do serviço usada para construir o campo de assinatura. O OneLake dá suporte à versão '10/02/2020', todas as versões após '06/12/2020' e versões antes de '10/02/2020'.
`signedResource`	`sr`	Obrigatório	Especifica quais recursos estão acessíveis pela assinatura de acesso compartilhado. Somente blob (`b`) e diretório (`d`) são aplicáveis ao OneLake.
`signedStart`	`st`	Opcional	A hora em que a assinatura de acesso compartilhado se torna válida. Formato UTC ISO 8601.
`signedExpiry`	`se`	Obrigatório	A hora em que a assinatura de acesso compartilhado expira
`signedPermissions`	`sp`	Obrigatório	Indica quais operações a SAS pode executar no recurso. Mais detalhes na seção Especificar permissões
`signedObjectId`	`skoid`	Obrigatório	Identifica uma entidade de segurança do Microsoft Entra.
`signedtenantId`	`sktid`	Obrigatório	Especifica o locatário do Microsoft Entra no qual uma entidade de segurança é definida.
`signedKeyStartTime`	`skt`	Opcional	Hora em UTC quando a chave de assinatura é iniciada. Retornada pela operação Obter Chave de Delegação do Usuário.
`signedKeyExpiryTime`	`ske`	Obrigatório	Hora em UTC quando a chave de assinatura termina. Retornada pela operação Obter Chave de Delegação do Usuário.
`signedKeyVersion`	`skv`	Obrigatório	A versão do serviço de armazenamento usada para obter a chave de delegação do usuário. Retornada pela operação Obter Chave de Delegação do Usuário. O OneLake dá suporte às versões 10/02/2020 e anteriores e versões após 06/12/2020
`signedKeyService`	`sks`	Obrigatório	O serviço válido para a chave de delegação do usuário. O OneLake só dá suporte ao Armazenamento de Blobs (`sks=b`).
`signature`	`sig`	Obrigatório	A assinatura é um HMAC (Hash-based Message Authentication Code) computado sobre a cadeia de caracteres para assinar e a chave usando o algoritmo SHA256 e codificado com codificação Base64.
`signedAuthorizedObjectId`	`saoid`	Sem suporte	A SAS do OneLake não dá suporte a esse recurso.
`signedUnauthorizedObjectId`	`suoid`	Sem suporte	A SAS do OneLake não dá suporte a esse recurso.
`signedCorrelationId`	`suoid`	Sem suporte	A SAS do OneLake não dá suporte a esse parâmetro.
`signedDirectoryDepth`	`sdd`	Opcional	Indica o número de diretórios dentro da pasta raiz do diretório especificado no campo canonicalizedResource da cadeia de caracteres para o sinal. Com suporte somente quando `sr=d`.
`signedEncryptionScope`	`ses`	Sem suporte	Atualmente, a SAS do OneLake não dá suporte a escopos de criptografia personalizados.
`signedIP`	`sip`	Sem suporte	Atualmente, a SAS do OneLake não dá suporte à filtragem de IP
`signedProtocol`	`spr`	Opcional	O OneLake só dá suporte a solicitações https.
`Cache-Control` cabeçalho de resposta	`rscc`	Sem suporte	A SAS do OneLake não dá suporte a esse parâmetro.
`Content-Disposition` cabeçalho de resposta	`rscd`	Sem suporte	A SAS do OneLake não dá suporte a esse parâmetro.
`Content-Encoding` cabeçalho de resposta	`rsce`	Sem suporte	A SAS do OneLake não dá suporte a esse parâmetro.
`Content-Language` cabeçalho de resposta	`rscl`	Sem suporte	A SAS do OneLake não dá suporte a esse parâmetro.
`Content Type` cabeçalho de resposta	`rsct`	Sem suporte	A SAS do OneLake não dá suporte a esse parâmetro.

Especifique as permissões

As permissões especificadas no signedPermissions campo (sp) no token da SAS indicam quais operações um cliente que possui a SAS pode executar no recurso.

As permissões podem ser combinadas para permitir que um cliente execute várias operações com a mesma SAS. Ao construir a SAS, inclua permissões na seguinte ordem: racwdxltmeop.

Exemplos de configurações de permissão válidas incluem rw, rd, rl, wd, wl e rl. Não é possível especificar uma permissão mais de uma vez.

Para garantir a paridade com as ferramentas do Armazenamento do Microsoft Azure existentes, o OneLake usa o mesmo formato de permissão que o Armazenamento do Microsoft Azure. O OneLake avalia as permissões concedidas a uma SAS em signedPermissions, as permissões da identidade de assinatura no Fabric e quaisquer funções de acesso a dados do OneLake, se aplicável. Lembre-se de que algumas operações, como definir permissões ou excluir espaços de trabalho, não são permitidas no OneLake por meio de APIs de Armazenamento do Microsoft Azure em geral e, portanto, conceder essa permissão (sp=op) não permitirá que uma SAS do OneLake execute essas operações.

Permissão	Símbolo de URI	Recurso	Operações permitidas
Ler	r	Diretório, Blob	Leia o conteúdo, a lista de bloqueios, as propriedades e os metadados de qualquer blob no contêiner ou diretório. Use um blob como a origem de uma operação de cópia.
Add	um	Diretório, Blob	Adicione um bloco a um blob de acréscimo.
Criar	c	Diretório, Blob	Escreva um novo blob, instantâneo de um blob ou copie um blob para um novo blob.
Gravar	w	Diretório, Blob	Crie ou grave conteúdo, propriedades, metadados ou lista de contatos bloqueados. Crie um instantâneo ou conceda o blob. Use o blob como o destino de uma operação de cópia.
Excluir	d	Diretório, Blob	Excluir um blob.
Excluir a versão	x	Blob	Excluir a versão do blob.
Exclusão permanente	y	Blob	Exclua permanentemente um instantâneo de blob ou uma versão.
Lista	l	Diretório	Listar blobs de forma não recorrente.
Marcações	t	Blob	Fazer leitura ou gravar as marcas em um blob.
Mover	m	Diretório, Blob	Mover um blob ou um diretório e seu conteúdo para um novo local.
Executar	e	Diretório, Blob	Obtenha as propriedades do sistema e, se o namespace hierárquico estiver habilitado para a conta de armazenamento, obtenha a ACL POSIX de um blob.
Propriedade	o	Diretório, Blob	Defina o proprietário ou o grupo proprietário. Sem suporte no OneLake
Permissões	p	Diretório, Blob	Definir as permissões. Sem suporte no OneLake
Definir Política de Imutabilidade	i	Blob	Defina ou exclua a política de imutabilidade ou a retenção legal em um blob.

Especifique a assinatura

O signature campo (sig) é usado para autorizar uma solicitação feita por um cliente com a assinatura de acesso compartilhado. A cadeia de caracteres a assinar é uma cadeia de caracteres exclusiva que é construída a partir dos campos que devem ser verificados para autorizar a solicitação. A assinatura é um HMAC que é computado sobre a cadeia de caracteres para o sinal e a chave usando o algoritmo SHA256 e codificado usando a codificação bBase65.

Para construir a cadeia de caracteres de assinatura de uma SAS de delegação de usuário, crie a cadeia de caracteres a partir dos campos feitos pela solicitação, codifique a cadeia de caracteres como UTF-8 e compute a assinatura usando o algoritmo HMAC-SHA256. Os campos incluídos na cadeia de caracteres para assinar devem ser decodificados para URL.

Os campos necessários na cadeia de caracteres para assinar dependem da versão de serviço usada para o campo autorização (sv). A seção a seguir descreve as configurações de cadeia de caracteres para assinar para versões que dão suporte ás SASs do OneLake.

Versão 06/12/2020 e posterior

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                signedEncryptionScope + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

Versão 10/01/2020

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

Versões anteriores à 10/02/2020

StringToSign =  signedPermissions + "\n" +  
                signedStart + "\n" +  
                signedExpiry + "\n" +  
                canonicalizedResource + "\n" +  
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +  
                signedProtocol + "\n" +  
                signedVersion + "\n" +  
                signedResource + "\n" +
                rscc + "\n" +
                rscd + "\n" +  
                rsce + "\n" +  
                rscl + "\n" +  
                rsct

Recurso canonizado

A parte de canonicalizedResource da cadeia de caracteres é um caminho canônico para o recurso. Ele deve incluir o ponto de extremidade do OneLake e o nome do recurso e deve ser decodificado por URL. Um caminho do OneLake deve incluir seu espaço de trabalho e um caminho de diretório deve incluir o número de subdiretórios que correspondem ao parâmetro sdd.

Os exemplos a seguir mostram como converter o URL do OneLake no recurso canônico correspondente. Lembre-se de que o OneLake dá suporte a operações do DFS e Blob e pontos de extremidade, e que o nome da conta para seu OneLake é sempre onelake.

Arquivo Blob

URL = https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv"

Diretório do DFS

URL = https://onelake.dfs.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/"

Exemplo de SAS do OneLake

O exemplo a seguir mostra um URI de SAS do OneLake com um token da SAS do OneLake acrescentado a ele. O token da SAS fornece permissões de leitura e gravação para a pasta Arquivos no lakehouse.

https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/?sp=rw&st=2023-05-24T01:13:55Z&se=2023-05-24T09:13:55Z&skoid=<object-id>&sktid=<tenant-id>&skt=2023-05-24T01:13:55Z&ske=2023-05-24T09:13:55Z&sks=b&skv=2022-11-02&sv=2022-11-02&sr=d&sig=<signature>

Compartilhar via

Criar uma SAS (assinatura de acesso compartilhado) do OneLake (versão prévia)

Atribuir permissões

Adquirir um token OAuth 2.0

Solicitar a chave de delegação do usuário

Construir uma SAS de delegação de usuário

Especifique as permissões

Especifique a assinatura

Versão 06/12/2020 e posterior

Versão 10/01/2020

Versões anteriores à 10/02/2020

Recurso canonizado

Arquivo Blob

Diretório do DFS

Exemplo de SAS do OneLake

Comentários

Recursos adicionais

Compartilhar via

Criar uma SAS (assinatura de acesso compartilhado) do OneLake (versão prévia)

Atribuir permissões

Adquirir um token OAuth 2.0

Solicitar a chave de delegação do usuário

Construir uma SAS de delegação de usuário

Especifique as permissões

Especifique a assinatura

Versão 06/12/2020 e posterior

Versão 10/01/2020

Versões anteriores à 10/02/2020

Recurso canonizado

Arquivo Blob

Diretório do DFS

Exemplo de SAS do OneLake

Conteúdo relacionado

Comentários

Recursos adicionais