Accorder un accès limité aux fichiers Dataverse à l’aide de signatures d’accès partagé

Pendant une heure, toute personne peut télécharger un fichier stocké dans Dataverse à l’aide d’une URL générée avec le message GetFileSasUrl. Cette URL fournit un accès anonyme à toute personne pendant cette heure, à partir du moment où l’URL est générée. La personne qui appelle GetFileSasUrl pour générer l’URL doit avoir accès à l’enregistrement contenant le fichier.

Les fichiers peuvent être des pièces jointes, des notes, des colonnes de fichiers ou des colonnes d’images. Certaines limitations s’appliquent

Paramètres

Le message GetFileSasUrl a les paramètres suivants :

Nom	Type	Description
Target	EntityReference/ crmbaseentity	Identifie la ligne de la table avec les données du fichier ou de l’image.
FileAttributeName	chaîne	Identifie le nom de la colonne de fichier ou d’image avec les données. Pour les enregistrements de notes et d’attributs, cette valeur doit être une chaîne vide.
DataSource	chaîne	Valeur « retained » ou « bin » lorsque l’enregistrement a été marqué pour la conservation des données à long terme ou supprimé dans une table avec la fonction de corbeille activée.

Réponse

Les données renvoyées par le message GetFileSasUrl ont une propriété Result avec ces données :

Nom	Type	Description
FileName	chaîne	Nom du fichier.
FileSizeInBytes	int64	Taille du fichier en octets.
MimeType	chaîne	Type MIME du fichier.
SasUrl	chaîne	URL de la signature d’accès partagé (SAS) qui peut être utilisée pour accéder au fichier.

Exemples

Ces exemples de fonctions montrent comment utiliser le message GetFileSasUrl avec le SDK pour .NET et l’API Web.

SDK pour .NET

Cette méthode statique GetFileSasUrl utilise les classes GetFileSasUrlRequest et GetFileSasUrlResponse. La propriété GetFileSasUrlResponse.Response.Result renvoie une instance de la classe FileSasUrlResponse avec les informations nécessaires pour télécharger un fichier de manière anonyme.

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

Utiliser le SDK pour .NET

API web

Cette fonction PowerShell Get-FileSasUrl utilise la fonction GetFileSasUrl qui renvoie un type complexe GetFileSasUrlResponse. La propriété GetFileSasUrlResponse.Result renvoie une instance du type complexe FileSasUrlResponse avec les informations nécessaires pour télécharger un fichier de manière anonyme.

Cette fonction dépend des variables globales $baseURI et $baseHeaders définies par la fonction Connect décrite dans Utiliser PowerShell et Visual Studio Code avec l’API web 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
}

Les exemples suivants illustrent les règles de définition du paramètre FileAttributeName. Il s’agit d’un paramètre obligatoire, mais il peut contenir une chaîne vide pour les ensembles d’entités annotations et 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>)'}

Utiliser l’API Web Microsoft Dataverse

Limitations

Les restrictions suivantes s’appliquent :

• GetFileSasUrl ne fonctionne que pour les colonnes d’images configurées pour prendre en charge les images de taille réelle. Apprenez à détecter quelles colonnes d’images prennent en charge les images de taille réelle
• GetFileSasUrl ne fonctionne pas pour les environnements qui continuent à utiliser la fonctionnalité de clé de chiffrement de base de données auto-gérée (BYOK). Les clients utilisant BYOK doivent migrer pour utiliser la clé gérée par le client (CMK) pour utiliser GetFileSasUrl.

Voir aussi

Vue d’ensemble des fichiers et des images
Utiliser les données de colonne de fichier
Utiliser les données de colonne d’image
Utiliser des données de fichier avec des enregistrements de pièce jointe et de note