Conceder acceso limitado a Dataverse archivos mediante firmas de acceso compartido

Durante una hora, cualquiera puede descargar un archivo almacenado en Dataverse usando una URL generada mediante el comando GetFileSasUrl. Esta URL proporciona acceso anónimo a cualquier persona durante esta hora, a partir del momento en que se genera la URL. La persona que invoca GetFileSasUrl para generar la URL debe tener acceso al registro que contiene el archivo.

Los archivos pueden ser archivos adjuntos, notas, columnas de archivos o columnas de imágenes. Existen algunas limitaciones

Nota

Los administradores pueden configurar el inquilino para limitar las descargas en función de la dirección IP de las aplicaciones cliente mediante la característica de restricción IP de SAS (versión preliminar). Cuando esta opción está habilitada, los usuarios recibirán un error 401 cuando la dirección IP de su equipo no cumpla con las restricciones establecidas para el inquilino e intenten descargar el archivo.

Parámetros

El mensaje GetFileSasUrl tiene los siguientes parámetros:

Nombre.	Type	Description
Target	EntityReference/ crmbaseentity	Identifica la fila de la tabla con los datos del archivo o imagen.
FileAttributeName	string	Identifica el nombre de la columna del archivo o de la imagen con los datos. Para registros de notas y atributos, este valor debe ser una cadena vacía.
DataSource	string	Un valor de "retained" o "bin" cuando el registro fue señalado para retención de datos a largo plazo o se eliminó en una tabla con la característica de papelera de reciclaje habilitada.

Response

Los datos devueltos por el mensaje GetFileSasUrl tienen una propiedad con estos datos Result :

Nombre.	Type	Description
FileName	string	Nombre de archivo.
FileSizeInBytes	int64	El tamaño del archivo en bytes.
MimeType	string	El tipo MIME del archivo.
SasUrl	string	La URL de la firma de acceso compartido (SAS) que se puede utilizar para acceder al archivo.

Ejemplos

Estas funciones de ejemplo muestran cómo utilizar el mensaje GetFileSasUrl con SDK para .NET y API de Web.

SDK para .NET

Este método GetFileSasUrl estático utiliza las clases GetFileSasUrlRequest y GetFileSasUrlResponse . La propiedad GetFileSasUrlResponse.Result devuelve una instancia de clase FileSasUrlResponse con la información necesaria para descargar un archivo de forma anónima.

/// <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;        
}

Utilice el SDK para .NET

API web

Esta Get-FileSasUrl función de PowerShell utiliza la función GetFileSasUrl que devuelve un tipo complejo GetFileSasUrlResponse. La propiedad GetFileSasUrlResponse.Result es una instancia de tipo complejo FileSasUrlResponse con la información necesaria para descargar un archivo de forma anónima.

Esta función depende de las variables globales $baseURI y $baseHeaders establecidas por la función de conexión descrita en Usar PowerShell y Visual Studio Code con la web API de 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
}

Los siguientes ejemplos demuestran las reglas para configurar el parámetro FileAttributeName . Es un parámetro obligatorio, pero puede contener una cadena vacía para conjuntos de entidades annotations y activitymimeattachments.

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>)'}

Usar la API web de Microsoft Dataverse

Limitaciones

Se presentan las siguientes limitaciones:

• GetFileSasUrl solo funciona para columnas de imágenes configuradas para admitir imágenes de tamaño completo. Aprenda a detectar qué columnas de imágenes admiten imágenes de tamaño completo
• GetFileSasUrl no funciona en entornos que continúan utilizando la función de clave de cifrado de base de datos autogestionada (BYOK). Los clientes que usan BYOK deben migrar para usar la clave administrada por el cliente (CMK)GetFileSasUrl.

Consulte también

Información general sobre imágenes y archivos
Usar datos de columna de archivo
Usar datos de columna de imagen
Usar datos de archivo con registros de Adjuntos y Notas