Gewähren Sie mithilfe von Shared Access Signatures eingeschränkten Zugriff auf Dataverse Dateien.

Eine Stunde lang kann jeder mithilfe einer mit der GetFileSasUrl-Nachricht generierten URL eine in Dataverse gespeicherte Datei herunterladen. Diese URL bietet jedem während dieser Stunde anonymen Zugriff, beginnend mit der Generierung der URL. Die Person, welche GetFileSasUrl zum Generieren der URL aufruft, muss Zugriff auf den Datensatz haben, der die Datei enthält.

Dateien können Anhänge, Notizen, Dateispalten oder Bildspalten sein. Es gelten einige Einschränkungen

Parameter

Die GetFileSasUrl-Nachricht hat die folgenden Parameter:

Name des Dataflows	typ	Beschreibung
Target	EntityReference/ crmbaseentity	Identifiziert die Tabellenzeile mit den Datei- oder Bilddaten.
FileAttributeName	string	Identifiziert den Namen der Datei- oder Bildspalte mit den Daten. Bei Notiz- und Attributdatensätzen muss dieser Wert eine leere Zeichenfolge sein.
DataSource	string	Ein Wert von retained oder bin, wenn der Datensatz für die langfristige Datenaufbewahrung gekennzeichnet oder in einer Tabelle mit der aktivierten Papierkorbfunktion gelöscht wurde.

Antworten

Die von der GetFileSasUrl Nachricht zurückgegebenen Daten haben eine Result Eigenschaft mit diesen Daten:

Name des Dataflows	typ	Beschreibung
FileName	string	Der Dateiname.
FileSizeInBytes	int64	Die Größe der Datei in Byte.
MimeType	string	Der MIME-Medientyp der Datei.
SasUrl	string	Die Shared Access Signature (SAS)-URL, die für den Zugriff auf die Datei verwendet werden kann.

Beispiele

Diese Beispielfunktionen zeigen, wie die GetFileSasUrl-Nachricht sowohl mit dem SDK für .NET als auch mit der Web-API verwendet wird.

SDK für .NET

Diese statische GetFileSasUrl-Methode verwendet die Klassen GetFileSasUrlRequest und GetFileSasUrlResponse. Die GetFileSasUrlResponse.Result-Eigenschaft gibt eine Instanz der FileSasUrlResponse-Klasse mit den zum anonymen Herunterladen einer Datei erforderlichen Informationen zurück.

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

Das SDK für .NET verwenden

Web-API

Diese Get-FileSasUrl-PowerShell-Funktion verwendet die GetFileSasUrl-Funktion, die einen komplexen GetFileSasUrlResponse-Typ zurückgibt. Die GetFileSasUrlResponse.Result-Eigenschaft ist eine Instanz vom komplexen FileSasUrlResponse-Typ mit den Informationen, die zum anonymen Herunterladen einer Datei erforderlich sind.

Diese Funktion hängt von den globalen Variablen $baseURI und $baseHeaders ab, die von der Connect-Funktion festgelegt werden, die unter PowerShell- und Visual Studio Code mit der Dataverse Web-API verwenden beschrieben ist

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
}

Die folgenden Beispiele demonstrieren die Regeln zum Setzen des Parameters FileAttributeName . Es handelt sich um einen erforderlichen Parameter, der jedoch für annotations und activitymimeattachments Entitätssätze eine leere Zeichenfolge enthalten kann.

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

Verwenden der Microsoft Dataverse-Web-API

Einschränkungen

Die folgenden Einschränkungen gelten:

• GetFileSasUrl funktioniert nur für Bildspalten, die für die Unterstützung von Bildern in voller Größe konfiguriert sind. Erfahren Sie, wie Sie erkennen, welche Bildspalten Bilder in voller Größe unterstützen.
• GetFileSasUrl funktioniert nicht für Umgebungen, die weiterhin das Feature zur Verwaltung des Datenbankverschlüsselungsschlüssels (BYOK) verwenden. Kundschaft, die BYOK verwendet, muss auf die Verwendung von kundenseitig verwalteten Schlüssels (CMK) umstellen, um GetFileSasUrl verwenden zu können.

Siehe auch

Dateien und Bilder – Übersicht
Dateispaltendaten verwenden
Bildspaltendaten verwenden
Dateidaten mit Anlagen- und Notizdatensätzen verwenden