Criar uma assinatura de acesso compartilhado (SAS) do OneLake (Visualização)
Você pode criar um OneLake SAS para fornecer acesso delegado de curto prazo a uma pasta ou arquivo no OneLake apoiado por suas credenciais do Microsoft Entra. O OneLake SAS 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 OneLake, você deve primeiro solicitar 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 de usuário. O OneLake SAS pode conceder acesso a arquivos e pastas apenas em itens de dados e não pode ser usado para operações de gerenciamento, como criar ou excluir itens ou espaços de trabalho.
Uma SAS OneLake pode conceder acesso a arquivos e pastas apenas 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 OneLake é criada de forma semelhante à SAS delegada pelo usuário do Armazenamento do Azure, usando os mesmos parâmetros para compatibilidade com ferramentas e aplicativos compatíveis com o Armazenamento do Azure.
Importante
Este recurso está em pré-visualização.
Atribuir permissões
Solicitar uma chave de delegação de usuário é uma operação de nível de 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 da Malha. A identidade do usuário solicitante é usada para autenticar o SAS, o que significa que o usuário deve ter permissão para os dados aos quais concede acesso ao SAS.
Adquira 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 aplicativos.
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 SAS de delegação de usuário. Esses parâmetros são descritos na referência Obter chave de delegação de usuário e na próxima seção.
Quando um cliente solicita uma chave de delegação de usuário usando um token OAuth 2.0, o OneLake retorna uma chave de delegação de usuário em nome do cliente. Uma SAS criada com essa chave de delegação de usuário recebe no máximo as permissões concedidas ao cliente, com escopo até as permissões explicitamente concedidas na SAS.
Você pode criar qualquer número de SASs OneLake para o tempo de vida da chave de delegação do usuário. No entanto, um OneLake SAS e chaves de delegação de usuário podem ser válidos 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 mais curtas do que o tempo de vida máximo de uma SAS delegada de um usuário do Armazenamento do Azure.
Construir uma SAS de delegação de usuário
A tabela a seguir resume os campos suportados para um token SAS OneLake. As seções subsequentes fornecem mais detalhes sobre esses parâmetros e como eles diferem dos tokens SAS do Armazenamento do Azure. O OneLake não oferece suporte a todos os parâmetros opcionais suportados pelo Armazenamento do Azure, e um OneLake SAS construído com um parâmetro sem suporte será rejeitado.
| Nome do campo SAS | Parâmetro de token SAS | Status | Description |
|---|---|---|---|
signedVersion |
sv |
Obrigatório | Indica a versão do serviço usada para construir o campo de assinatura. O OneLake suporta a versão '2020-02-10', todas as versões após '2020-12-06' e versões anteriores a '2020-02-10'. |
signedResource |
sr |
Necessário | Especifica quais recursos podem ser acessados por meio da assinatura de acesso compartilhado. Apenas 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 ISO 8601 UTC. |
signedExpiry |
se |
Necessário | A hora em que a assinatura de acesso compartilhado expira |
signedPermissions |
sp |
Necessário | Indica quais operações o SAS pode executar no recurso. Mais detalhes na seção Especificar permissões |
signedObjectId |
skoid |
Necessário | Identifica uma entidade de segurança do Microsoft Entra. |
signedtenantId |
sktid |
Necessá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. Retornado pela operação Obter chave de delegação de usuário. |
signedKeyExpiryTime |
ske |
Necessário | Hora em UTC quando a chave de assinatura termina. Retornado pela operação Obter chave de delegação de usuário. |
signedKeyVersion |
skv |
Necessário | A versão do serviço de armazenamento usada para obter a chave de delegação do usuário. Retornado pela operação Obter chave de delegação de usuário. O OneLake suporta versões 2020-02-10 e anteriores, e versões posteriores a 2020-12-06 |
signedKeyService |
sks |
Necessário | O serviço válido para a chave de delegação do usuário. O OneLake suporta apenas o armazenamento de Blob (sks=b). |
signature |
sig |
Necessário | A assinatura é um código de autenticação de mensagem baseado em hash (HMAC) calculado sobre a cadeia de caracteres para assinar e chave usando o algoritmo SHA256 e, em seguida, codificado com codificação Base64. |
signedAuthorizedObjectId |
saoid |
Não suportado | O OneLake SAS não suporta esse recurso. |
signedUnauthorizedObjectId |
suoid |
Não suportado | O OneLake SAS não suporta esse recurso. |
signedCorrelationId |
suoid |
Não suportado | OneLake SAS não suporta este parâmetro. |
signedDirectoryDepth |
sdd |
Opcional | Indica o número de diretórios dentro da pasta raiz do diretório especificado no campo canonicalizedResource da string-to-sign. Suportado apenas quando sr=d. |
signedEncryptionScope |
ses |
Não suportado | Atualmente, o OneLake SAS não oferece suporte a escopos de criptografia personalizados. |
signedIP |
sip |
Não suportado | Atualmente, o OneLake SAS não suporta filtragem de IP |
signedProtocol |
spr |
Opcional | O OneLake suporta apenas solicitações https. |
Cache-Control cabeçalho de resposta |
rscc |
Não suportado | OneLake SAS não suporta este parâmetro. |
Content-Disposition cabeçalho de resposta |
rscd |
Não suportado | OneLake SAS não suporta este parâmetro. |
Content-Encoding cabeçalho de resposta |
rsce |
Não suportado | OneLake SAS não suporta este parâmetro. |
Content-Language cabeçalho de resposta |
rscl |
Não suportado | OneLake SAS não suporta este parâmetro. |
Content Type cabeçalho de resposta |
rsct |
Não suportado | OneLake SAS não suporta este parâmetro. |
Especificar permissões
As permissões especificadas no signedPermissions campo (sp) no token SAS indicam quais operações um cliente que possui o 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, você deve incluir permissões na seguinte ordem: racwdxltmeop.
Exemplos de configurações de permissão válidas incluem rw, rd, rl, wd, wle rl. Não é possível especificar uma permissão mais de uma vez.
Para garantir a paridade com as ferramentas de Armazenamento do Azure existentes, o OneLake usa o mesmo formato de permissão que o Armazenamento do Azure. O OneLake avalia as permissões concedidas a uma SAS no signedPermissions, as permissões da identidade de assinatura na Malha 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 Azure em geral e, portanto, conceder essa permissão (sp=op) não permitirá que um SAS OneLake execute essas operações.
| Permissão | Símbolo URI | Recurso | Operações permitidas |
|---|---|---|---|
| Lida | 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. |
| Adicionar | a | Diretório, Blob | Adicione um bloco a um blob de acréscimo. |
| Criar | c | Diretório, Blob | Escreva um novo blob, crie um snapshot de um blob ou copie um blob para um novo blob. |
| Escrita | w | Diretório, Blob | Crie ou escreva conteúdo, propriedades, metadados ou lista de bloqueio. Snapshot ou lease o blob. Use o blob como o destino de uma operação de cópia. |
| Delete | d | Diretório, Blob | Exclua um blob. |
| Excluir versão | x | Blob | Exclua uma versão de blob. |
| Eliminar de forma permanente | S | Blob | Exclua permanentemente um instantâneo ou versão de blob. |
| Listagem | l | Diretório | Listar blobs de forma não recursiva. |
| Etiquetas | t | Blob | Leia ou escreva as tags em um blob. |
| Mover | m | Diretório, Blob | Mova 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 | Defina as permissões. Sem suporte no OneLake |
| Definir política de imutabilidade | posso | 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 para sinal é uma cadeia de caracteres exclusiva construída a partir dos campos que devem ser verificados para autorizar a solicitação. A assinatura é um HMAC que é calculado sobre a cadeia de caracteres para assinar e a chave usando o algoritmo SHA256 e, em seguida, 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 para assinar a partir dos campos feitos pela solicitação, codifique a cadeia de caracteres como UTF-8 e, em seguida, calcule a assinatura usando o algoritmo HMAC-SHA256. Os campos incluídos na cadeia de caracteres para assinar devem ser decodificados por URL.
Os campos obrigatórios na cadeia de caracteres para assinar dependem da versão do serviço usada para o campo de autorização (sv). A seção a seguir descreve as configurações de cadeia de caracteres para assinar para versões que suportam SASs OneLake.
Versão 2020-12-06 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 2020-01-10
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 a 2020-02-10
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 canonicalizado
A canonicalizedResource parte da cadeia de caracteres é um caminho canônico para o recurso. Ele deve incluir o ponto de extremidade OneLake e o nome do recurso, e deve ser decodificado por URL. Um caminho 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 sdd parâmetro.
Os exemplos a seguir mostram como converter sua URL do OneLake para o recurso canonicalizado correspondente. Lembre-se de que o OneLake suporta operações e pontos de extremidade DFS e Blob e que o nome da conta do 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 DFS
URL = https://onelake.dfs.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/"
Exemplo de OneLake SAS
O exemplo a seguir mostra um URI SAS OneLake com um token SAS OneLake anexado a ele. O token SAS fornece permissões de leitura e gravação para a pasta Files na 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>