Conceder acesso limitado a arquivos do Dataverse usando assinaturas de acesso compartilhado

Por uma hora, qualquer pessoa pode baixar um arquivo armazenado no Dataverse usando uma URL gerada usando a GetFileSasUrl mensagem. Essa URL fornece acesso anônimo para qualquer pessoa durante esta hora, começando quando a URL é gerada. A pessoa que está chamando GetFileSasUrl para gerar a URL deve ter acesso ao registro que contém o arquivo.

Os arquivos podem ser anexos, anotações, colunas de arquivo ou colunas de imagem. Algumas limitações se aplicam

Note

Os administradores podem configurar o tenant para limitar os downloads com base no IP dos aplicativos cliente usando o recurso de restrição de IP SAS (versão prévia). Quando estiver habilitado, os usuários receberão um erro 401 quando o endereço IP do computador não atender às restrições definidas para o locatário e tentarem baixar o arquivo.

Parameters

A GetFileSasUrl mensagem tem os seguintes parâmetros:

Name	Tipo	Description
Target	Entityreference/ crmbaseentity	Identifica a linha da tabela com os dados de arquivo ou imagem.
FileAttributeName	cadeia	Identifica o nome do arquivo ou da coluna de imagem com os dados. Para registros de anotação e atributo, esse valor deve ser uma cadeia de caracteres vazia.
DataSource	cadeia	Um valor "retained" ou "bin" quando o registro foi sinalizado para retenção de dados de longo prazo ou excluído em uma tabela com a manutenção de registros excluídos ativada.

Resposta

Os dados retornados pela mensagem GetFileSasUrl têm a propriedade Result com estes dados:

Name	Tipo	Description
FileName	cadeia	O nome do arquivo.
FileSizeInBytes	int64	O tamanho do arquivo em bytes.
MimeType	cadeia	O tipo de mime do arquivo.
SasUrl	cadeia	A URL de SAS (assinatura de acesso compartilhado) que pode ser usada para acessar o arquivo.

Exemplos

Essas funções de exemplo mostram como usar a mensagem GetFileSasUrl com o SDK para .NET e a API Web.

SDK para .NET

Esse método estático GetFileSasUrl usa as classes GetFileSasUrlRequest e GetFileSasUrlResponse. A propriedade GetFileSasUrlResponse.Result retorna uma instância de classe FileSasUrlResponse com informações necessárias para baixar anonimamente um arquivo.

/// <summary>
/// Generates a link for anonymous access to a file.
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance.</param>
/// <param name="target">The record that has the file data.</param>
/// <param name="fileAttributeName">Optional name of the file or image column</param>
/// <param name="dataSource">Optional source of the data when retained or deleted.</param>
/// <returns>Information to download a file</returns>
static FileSasUrlResponse GetFileSasUrl(IOrganizationService service, 
    EntityReference target, 
    string? fileAttributeName = null, 
    string? dataSource = null) { 

    var request = new GetFileSasUrlRequest() { 
        Target = target
    };

    if (target.LogicalName == "annotation" ||
        target.LogicalName == "activitymimeattachment"){

        //FileAttributeName is required
        request.FileAttributeName = string.Empty;

    }
    else
    {

        if (!string.IsNullOrEmpty(fileAttributeName))
        {
            request.FileAttributeName = fileAttributeName;
        }
        else
        {

            string message = "fileAttributeName is required ";
            message += "when the target isn't annotation ";
            message += "or activitymimeattachment";

            throw new Exception(message);
        }
    }
    
    if (!string.IsNullOrEmpty(dataSource)) {
        //dataSource should be 'retained' or 'bin'
        request.DataSource = dataSource;
    }

   var response = (GetFileSasUrlResponse)service.Execute(request);

    return response.Result;        
}

Usar o SDK para .NET

Web API

Essa Get-FileSasUrl função do PowerShell usa a função GetFileSasUrl que retorna um tipo complexo GetFileSasUrlResponse. A GetFileSasUrlResponse.Result propriedade é uma instância de tipo complexo FileSasUrlResponse com informações necessárias para baixar um arquivo anonimamente.

Essa função depende das variáveis globais $baseURI e $baseHeaders definidas pela função Connect descritas em Use PowerShell e Visual Studio Code com a API Web do Dataverse

function Get-FileSasUrl {
   param (
      [Parameter(Mandatory)] 
      [string] 
      $setName,
      [Parameter(Mandatory)] 
      [guid] 
      $id,
      [string] 
      $columnName,
      [string] 
      $dataSource
   )

   $uri = $baseURI + "GetFileSasUrl(Target=@t,FileAttributeName=@f"

   $query = "?@t={'@odata.id':'$setName($id)'}&@f="

   if ($setName -eq 'annotations' -or $setName -eq 'activitymimeattachments') {

      $query += "''" # empty string
   }
   else {
      if ($null -ne $columnName) {

         $query += "'$columnName'"
      }
      else {

         $message = "columnName is required "
         $message += "when the setName isn't annotations "
         $message += "or activitymimeattachments"

         throw $message
         
      }
   }

   if("" -ne $dataSource) {
      $uri += ",DataSource=@d"
      # $dataSource should be 'retained' or 'bin'
      $query += "&@d='$dataSource'"
   }

   $GetFileSasUrlRequest = @{
      Uri     = $uri + ')' + $query
      Method  = 'Get'
      Headers = $baseHeaders
   }

   Invoke-RestMethod @GetFileSasUrlRequest | Select-Object -ExpandProperty Result
}

Os exemplos a seguir demonstram as regras para definir o FileAttributeName parâmetro. É um parâmetro necessário, mas pode conter uma cadeia de caracteres vazia para annotations e activitymimeattachments conjuntos de entidades.

GET [Organization URI]/api/data/v9.2/GetFileSasUrl(Target=@p1,FileAttributeName='')?@p1={'@odata.id':'annotations(<annotationid>)'}

GET [Organization URI]/api/data/v9.2/GetFileSasUrl(Target=@p1,FileAttributeName='')?@p1={'@odata.id':'activitymimeattachments(<activitymimeattachmentid>)'}

GET [Organization URI]/api/data/v9.2/GetFileSasUrl(Target=@p1,FileAttributeName='myattachment')?@p1={'@odata.id':'myfiles(<myfileid>)'}

Use a API Web do Microsoft Dataverse

Limitações

As seguintes limitações se aplicam:

• GetFileSasUrl funciona apenas para colunas de imagem configuradas para dar suporte a imagens em tamanho real. Saiba como detectar quais colunas de imagem dão suporte a imagens de tamanho completo
• GetFileSasUrl não funciona para ambientes que continuam a usar o recurso de chave de criptografia de banco de dados autogerenciada (BYOK). Os clientes que usam BYOK precisam migrar para usar a CMK (chave gerenciada pelo cliente) para usar GetFileSasUrl.

Consulte também

Visão geral de arquivos e imagens
Usar dados da coluna do arquivo
Usar dados de coluna da imagem
Usar dados de arquivo com registros de Anexo e Anotação