Obter chave de delegação de usuário

  • Artigo

A Get User Delegation Key operação obtém uma chave que pode ser usada para assinar uma SAS de delegação de usuário (assinatura de acesso compartilhado). Uma SAS de delegação de usuário concede acesso a recursos de Armazenamento de Blobs do Azure usando credenciais de Microsoft Entra. A Get User Delegation Key operação está disponível na versão 2018-11-09 e posterior.

Solicitação

Construa a operação Get User Delegation Key da seguinte forma. O HTTPS é necessário. Substitua myaccount pelo nome da sua conta de armazenamento.

URI de solicitação de método POST Versão HTTP
https://myaccount.blob.core.windows.net/?restype=service&comp=userdelegationkey HTTP/1.1

Solicitação de serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento local, especifique o nome do host local e a porta do Armazenamento de Blobs como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento local:

URI de solicitação de método POST Versão HTTP
http://127.0.0.1:10000/devstoreaccount1/?restype=service&comp=userdelegationkey HTTP/1.1

Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Parâmetros do URI

Os seguintes parâmetros adicionais podem ser especificados no URI de solicitação.

Parâmetro Descrição
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Armazenamento de Blobs.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação Descrição
Authorization Obrigatórios. Especifica o esquema de autorização. Há suporte apenas para autorização com Microsoft Entra ID. Para obter mais informações, consulte Autorizar com Microsoft Entra ID.
x-ms-version Necessário para todas as solicitações autorizadas. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres KiB (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar Armazenamento de Blobs do Azure.

Corpo da solicitação

Formato do corpo da solicitação:

<?xml version="1.0" encoding="utf-8"?>  
<KeyInfo>  
    <Start>String, formatted ISO Date</Start>
    <Expiry>String, formatted ISO Date </Expiry>
</KeyInfo>

Os elementos do corpo da solicitação são descritos na tabela a seguir:

Elemento Descrição
Iniciar Obrigatórios. A hora de início para a SAS de delegação de usuário, no formato de data ISO. Deve ser uma data e hora válidas dentro de sete dias a partir da data atual.
Termo Obrigatórios. O tempo de expiração da SAS de delegação do usuário, no formato de data ISO. Deve ser uma data e hora válidas dentro de sete dias a partir da data atual.

Resposta

A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta.

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK).

Para obter mais informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta Descrição
x-ms-request-id Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
x-ms-version A versão do Armazenamento de Blobs que foi usada para executar a solicitação.
Date Um valor de data/hora UTC gerado pelo serviço, que indica a hora em que a resposta foi iniciada.
x-ms-client-request-id Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho será igual ao valor do x-ms-client-request-id cabeçalho se ele estiver presente na solicitação e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, ele não estará presente na resposta.

Corpo da resposta

Formato do corpo da resposta:

<?xml version="1.0" encoding="utf-8"?>
<UserDelegationKey>
    <SignedOid>String containing a GUID value</SignedOid>
    <SignedTid>String containing a GUID value</SignedTid>
    <SignedStart>String formatted as ISO date</SignedStart>
    <SignedExpiry>String formatted as ISO date</SignedExpiry>
    <SignedService>b</SignedService>
    <SignedVersion>String specifying REST api version to use to create the user delegation key</SignedVersion>
    <Value>String containing the user delegation key</Value>
</UserDelegationKey>

Os elementos do corpo da resposta estão descritos na seguinte tabela:

Elemento Descrição
SignedOid O identificador imutável para um objeto no sistema de identidade da Microsoft.
SignedTid Um GUID que representa o locatário Microsoft Entra do qual o usuário é.
SignedStart A hora de início da chave de delegação do usuário, no formato de data ISO.
SignedExpiry O tempo de expiração da chave de delegação do usuário, no formato de data ISO.
SignedService O serviço para o qual a chave de delegação de usuário pode ser usada, no qual b representa o Armazenamento de Blobs.
SignedVersion A versão da API REST usada para obter a chave de delegação do usuário.
Valor A chave de delegação do usuário.

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Você só pode autorizar a Get User Delegation Key operação usando Microsoft Entra ID.

Permissões

A entidade de segurança que solicita a chave de delegação do usuário precisa ter as permissões apropriadas para fazer isso. Uma entidade de segurança Microsoft Entra pode ser um usuário, um grupo, uma entidade de serviço ou uma identidade gerenciada.

Veja abaixo a ação RBAC necessária para que uma entidade de segurança Microsoft Entra chame a Get User Delegation Key operação e a função RBAC interna do Azure com menos privilégios que inclui esta ação:

Qualquer função interna que inclua essa ação rbac do Azure, explicitamente ou como parte de uma definição curinga, tem permissão para chamar a Get User Delegation Key operação.

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Como a Get User Delegation Key operação atua no nível da conta de armazenamento, a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey deve ter o escopo definido no nível da conta de armazenamento, do grupo de recursos ou da assinatura. Se a entidade de segurança receber qualquer uma das funções internas listadas anteriormente ou uma função personalizada que inclua a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey , no nível da conta de armazenamento, do grupo de recursos ou da assinatura, a entidade de segurança poderá solicitar a chave de delegação do usuário.

Se a entidade de segurança receber uma função que permita o acesso a dados, mas estiver no escopo do nível de um contêiner, você também poderá atribuir a função Delegador de Blob de Armazenamento a essa entidade de segurança no nível da conta de armazenamento, do grupo de recursos ou da assinatura. A função Delegador de Blob de Armazenamento concede as permissões da entidade de segurança para solicitar a chave de delegação do usuário.

Para obter mais informações sobre funções RBAC para o Armazenamento do Azure, consulte Autorizar com o Azure Active Directory.

Comentários

Use a chave de delegação de usuário para criar uma SAS de delegação de usuário. Inclua os campos retornados na resposta ao Get User Delegation Key no token SAS de delegação de usuário. Para obter mais informações, consulte Criar uma SAS de delegação de usuário.

A chave de delegação do usuário não pode ser usada para acessar diretamente os recursos do Armazenamento de Blobs.

Cobrança

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para Get User Delegation Key solicitações com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de cobrança
Obter chave de delegação de usuário Blob de blocos Premium
Uso geral v2 Standard		 Outras operações
Obter chave de delegação de usuário Uso geral v1 Standard Operações de leitura

Para saber mais sobre os preços da categoria de cobrança especificada, confira Preços Armazenamento de Blobs do Azure.

Confira também