Verwenden von Bildspaltendaten in Microsoft Dataverse

Sie können Bilddaten in Microsoft Dataverse speichern, indem Sie Bildspalten oder Dateispalten verwenden. Bildspalten in Dataverse weisen spezielle Verhaltensweisen und Einschränkungen auf, die das Anzeigen von Bildern in Anwendungen unterstützen. Sie können viele der gleichen APIs für Dateispalten mit Bildspalten verwenden.

In der folgenden Tabelle werden einige der Unterschiede zwischen Bild- und Dateispalten vorgestellt.

Bild Datei
Dateigröße Begrenzt auf 30 MB. Bis zu 10 GB. Die API kann zwar Dateien mit einer Größe von bis zu 10 GB verarbeiten, dennoch unterstützen Power Apps Client-Steuerelemente derzeit nur Dateien mit bis zu 128 MB. Das Überschreiten des Werts 128 MB bei Verwendung dieser Steuerelemente führt zu Fehlern beim Hochladen oder Herunterladen von Dateien.
Dateitypen Nur Bilddateitypen Alle vom Organization.BlockedAttachments-Wert zugelassenen Dateitypen. Weitere Informationen: Bestimmte Dateitypen blockieren
Mit Aktualisierung einrichten Sie können Bildspaltendaten mit anderen Datensatzdaten mithilfe von Update aktualisieren. Sie können Dateien nur einzeln in Dateispalteneigenschaften hochladen.
Mit Aktualisierung löschen Sie können Bildspaltendaten löschen, indem Sie das Attribut oder die Eigenschaft auf null festlegen und dann den Datensatz aktualisieren. Weitere Informationen: Bilder löschen Sie können Dateispaltendaten nur mithilfe der DeleteFile Nachricht löschen oder eine DELETE Anforderung an die bestimmte Spalte mithilfe der Web-API senden. Weitere Informationen: Dateien löschen
Mit Erstellen festlegen Wenn die Bildspalte das primäre Bild ist, können Sie Bilddaten mit anderen Datensatzdaten mithilfe von create festlegen. Weitere Informationen: Primäre Bilder Sie können Dateien nur einzeln in Dateispalteneigenschaftenfeldern hochladen, nachdem der Datensatz erstellt wurde.
Mit Abrufen zurückgeben Sie können Bilder in Miniaturgröße zusammen mit anderen Datensatzdaten abrufen, indem Sie retrieve verwenden. Bei dem zurückgegebenen Wert handelt es sich um die Datei-ID. Weitere Informationen: Verhalten beim Abrufen
Download-URL Jede Bildspalte hat eine Zeichenfolgenspalte, die eine relative URL enthält, die Sie in eine Anwendung einfügen können, die das Herunterladen der Bilddatei ermöglicht. Weitere Informationen: URL herunterladen Es gibt keine Zeichenfolgenspalte mit einer URL zum Herunterladen, aber Sie können eine URL erstellen, um die Datei direkt von der Web-API herunterzuladen. Weitere Informationen: Eine Datei in eine einzelne Anforderungen über die Web-API herunterladen

Maximale Bildgröße

Genau wie Dateispalten können Sie die maximale Größe von Daten angeben, die in einer Bildspalte gespeichert sind, indem Sie die MaxSizeInKb Eigenschaft verwenden. Die maximal zulässige Größe beträgt jedoch 30 MB.

Wenn Sie versuchen, eine datei hochzuladen, die zu groß ist, wird die folgende Fehlermeldung angezeigt:

Name: ProcessImageFailure
Code: 0x80072553
Zahl: -2147015341
Meldung: Error occured when processing image. Reason: File size is too big. MaxSize: 0 MB, Uploaded filesize: 0 MB.

Verwenden Sie die folgenden Beispiele, um die maximale Dateigröße zu überprüfen:

Die folgende statische GetImageColumnMaxSizeInKb Methode gibt den MaxSizeInKB Wert für eine ImageAttributeMetadata Spalte zurück.

/// <summary>
/// Retrieves the MaxSizeInKb property of an image column.
/// </summary>
/// <param name="service">IOrganizationService</param>
/// <param name="entityLogicalName">The logical name of the table that has the column</param>
/// <param name="imageColumnLogicalName">The logical name of the image column.</param>
/// <returns></returns>
/// <exception cref="Exception"></exception>
public static int GetImageColumnMaxSizeInKb(
   IOrganizationService service, 
   string entityLogicalName, 
   string imageColumnLogicalName) 
{

   RetrieveAttributeRequest retrieveAttributeRequest = new() { 
         EntityLogicalName = entityLogicalName,
         LogicalName = imageColumnLogicalName
   };

   RetrieveAttributeResponse retrieveAttributeResponse;
   try
   {
         retrieveAttributeResponse = (RetrieveAttributeResponse)service.Execute(retrieveAttributeRequest);
   }
   catch (Exception)
   {
         throw;
   }

   if (retrieveAttributeResponse.AttributeMetadata is ImageAttributeMetadata imageColumn)
   {
         return imageColumn.MaxSizeInKB.Value;
   }
   else
   {
         throw new Exception($"{entityLogicalName}.{imageColumnLogicalName} is not a image column.");
   }
}

Weitere Informationen:

Bilddateitypen

Bildspalten speichern die folgenden binären Bildtypen:

Dateiformat MIME-Typ Dateierweiterungen
Graphics Interchange Format image/gif .gif
„Joint Photographic Expert Group“-Bild image/jpeg .jpg, .jpeg
Bitmap-Datei image/bmp .bmp
Portable Network Graphics image/png .png

Wenn Sie versuchen, eine Datei zu speichern, die keiner dieser Typen ist, wird die folgende Fehlermeldung angezeigt:

Name: ProcessImageFailure
Code: 0x80072553
Zahl: -2147015341
Meldung: Error occurred when processing image. Reason: Update image properties failed for objectid: <id of record>, logicalName: <logical name of table>, attribute: <logical name of image column

Bilder in voller Größe und in Miniaturansicht

Wenn Sie einen Bildspaltenwert festlegen, generiert Dataverse automatisch ein Miniaturbild, das für die Verwendung als Symbol in einer Anwendung geeignet ist.

Wenn Sie die Bildspalte so konfigurieren, dass ein Bild in voller Größe gespeichert wird, können Sie eine Datei bis zur konfigurierten Grenze MaxSizeInKb getrennt von der Miniaturbildgröße speichern und herunterladen. Die ImageAttributeMetadata.CanStoreFullImage-Eigenschaft steuert, ob eine Bildspalte ein Bild in voller Größe speichert.

Ermitteln, welche Bildspalten Bilder in voller Größe unterstützen

Verwenden Sie die RetrieveMetadataChanges Message, um Schemadefinitionen abzufragen und alle Image-Spalten abzurufen. Überprüfen Sie dann die ImageAttributeMetadata.CanStoreFullImage-Eigenschaft , um die Spalten zu identifizieren, die Bilder in voller Größe unterstützen. Weitere Informationen finden Sie unter Abfrageschemadefinitionen.

Hinweis

Die RetrieveMetadataChanges Nachricht unterstützt keine Filterung nach der ImageAttributeMetadata.CanStoreFullImage-Eigenschaft. Filtern Sie nach AttributeMetadata.AttributeTypeName , um alle Bildspalten zurückzugeben, und überprüfen Sie dann die CanStoreFullImage Eigenschaft in den Ergebnissen.

Die statische PrintFullSizedImageColumns Methode verwendet die RetrieveMetadataChangesRequest Klasse, um die logischen Namen von Tabellen und Bildspalten zu schreiben, die Bilder in voller Größe speichern können.

static void PrintFullSizedImageColumns(IOrganizationService service)
{
    EntityQueryExpression query = new()
    {
        Properties = new MetadataPropertiesExpression("LogicalName", "Attributes"),
        AttributeQuery = new AttributeQueryExpression
        {
            Properties = new MetadataPropertiesExpression(
                "LogicalName",
                "CanStoreFullImage"),
            Criteria = new MetadataFilterExpression(LogicalOperator.And)
            {
                Conditions =
                {
                    new MetadataConditionExpression(
                        propertyName: "AttributeTypeName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value: AttributeTypeDisplayName.ImageType)
                }
            }
        }
    };

    RetrieveMetadataChangesRequest request = new()
    {
        Query = query
    };

    RetrieveMetadataChangesResponse response =
        (RetrieveMetadataChangesResponse)service.Execute(request);

    foreach (EntityMetadata table in response.EntityMetadata)
    {
        foreach (ImageAttributeMetadata imageColumn in table.Attributes)
        {
            if (imageColumn.CanStoreFullImage == true)
            {
                Console.WriteLine($"{table.LogicalName}.{imageColumn.LogicalName}");
            }
        }
    }
}

Output

account.sample_sampleimage

Größenänderungsregeln für Bilder in Miniaturansicht

Um ein Bild in Miniaturansicht zu generieren, wird das Bild von Dataverse entsprechend den folgenden Regeln in eine quadratische Form beschnitten und skaliert.

  • Wenn mindestens eine Seite des Bilds größer als 144 Pixel ist, bezieht Dataverse das Bild in der Mitte auf 144 x 144 Pixel ab.
  • Wenn beide Seiten des Bilds kleiner als 144 Pixel sind, schneidet Dataverse das Bild quadratisch auf die kleinste Seite zu.

Die folgende Tabelle enthält zwei Beispiele.

Vorher Nach
Screenshot eines Bilds mit 300 x 428 Pixeln, bevor Dataverse die Größe auf eine Miniaturansicht ändert.

300x428		 Bild nach dem Ändern der Größe

144x144
Screenshot eines kleineren Bilds von 91 x 130 Pixeln, bevor Dataverse es auf ein Quadrat zuschneidet.

91x130		 Kleineres Bild nach Größenänderung

91x91

Primäre Bilder

Jede Tabelle kann mehrere Bildspalten aufweisen, Sie können jedoch nur eine Bildspalte als primäres Bild definieren. Sie können das primäre Image nur mithilfe eines Erstellungsvorgangs festlegen. Weitere Informationen finden Sie unter Festlegen nur primärer Images für den Erstellungsvorgang.

Die ImageAttributeMetadata.IsPrimaryImage-Eigenschaft steuert, welche Bildspalte das primäre Bild für die Tabelle darstellt.

Die EntityMetadata.PrimaryImageAttribute-Eigenschaft gibt den logischen Namen des Bildes, welches das aktuelle primäre Bild für die Tabelle ist.

Sie können auch die Tabelle Entity Image Configuration (EntityImageConfig) abfragen, um zu bestimmen, welche Bildspalten das aktuelle primäre Bild darstellen, indem Sie die Werte der parententitylogicalname- und primaryimageattribute-Spalten verwenden.

Die statische PrintPrimaryImageColumns Methode im folgenden Beispiel schreibt die Namen der Tabellen- und Bildspalten für alle primären Bildspalten.

static void PrintPrimaryImageColumns(IOrganizationService service)
{
    QueryExpression query = new QueryExpression("entityimageconfig")
    {
        ColumnSet = new ColumnSet("parententitylogicalname", "primaryimageattribute"),
    };

    EntityCollection response = service.RetrieveMultiple(query);
    foreach (Entity record in response.Entities)
    {
        Console.WriteLine($"{record["parententitylogicalname"]}.{record["primaryimageattribute"]}");
    }
}

Output

account.sample_sampleimage

Weitere Informationen: Erstellen von Abfragen mit QueryExpression

URL herunterladen

Jede Bildspalte hat die folgenden Begleitspalten, aber keine davon erscheint im Power Apps-Designer.

Spalte Typ Benennungskonvention Beschreibung
Bild-ID Eindeutiger Bezeichner <image column name>Id Ein eindeutiger Bezeichner für das Bild.
Zeitstempel BigInt <image column name>_Timestamp Gibt an, wann das Bild zuletzt aktualisiert wurde. Dieser Wert trägt dazu bei, sicherzustellen, dass die neueste Version des Images heruntergeladen wird, anstatt dass der Client eine zwischengespeicherte Version verwendet, die zuvor abgerufen wurde.
URL Zeichenfolge <image column name>_URL Eine relative URL zum Herunterladen einer Version des Bildes in Miniaturansicht

Die Spaltenwerte für die Bild-ID und den Zeitstempel haben keine Anwendungsfälle, außer dass sie innerhalb des URL-Zeichenfolgenspaltenwerts verwendet werden.

Wenn die Spalte für einen Datensatz Daten enthält, ist die Download-URL eine relative URL, die das folgende Format verwendet:

/Image/download.aspx?Entity=<entity logical name>&Attribute=<image column logical name>&Id=<image id value>&Timestamp=<time stamp value>

Sie können diesen Wert an den Organisations-URI anfügen, um eine URL zu erstellen, die Sie zum Herunterladen der Bilddatei in Miniaturansicht verwenden können. Zum Beispiel:

https://yourorg.crm.dynamics.com/Image/download.aspx?Entity=account&Attribute=sample_imagecolumn&Id=7a4814f9-b0b8-ea11-a812-000d3a122b89&Timestamp=637388308718090885

URL zum Herunterladen des Bildes in voller Größe

Wenn die Bildspalte so konfiguriert ist, dass Bilder in voller Größe gespeichert werden, können Sie die URL anfügen &Full=true und der Link lädt das Bild in voller Größe herunter. Zum Beispiel:

https://yourorg.crm.dynamics.com/Image/download.aspx?Entity=account&Attribute=sample_imagecolumn&Id=7a4814f9-b0b8-ea11-a812-000d3a122b89&Timestamp=637388308718090885&Full=true

Wenn die Spalte nicht zum Speichern von Bildern mit voller Größe konfiguriert ist, gibt die Anforderung keine Daten zurück.

Verwenden Sie Bilddaten mit Aufzeichnungen

Wenn Sie mit Datensätzen arbeiten, hängt die Behandlung von Bilddaten davon ab, ob Sie das SDK oder die Web-API verwenden.

Mit der folgenden statischen RetrieveAndUpdateImageColumn Methode wird ein byte[] Bildwert aus einer Spalte abgerufen, lokal gespeichert und ein neues Bild hochgeladen.

static void RetrieveAndUpdateImageColumn(
    IOrganizationService service,
    Guid accountid,
    string imageColumnLogicalName) 
{

    // Retrieve account with image
    Entity account = service.Retrieve(
        entityName: "account",
        id: accountid, 
        columnSet: new ColumnSet(imageColumnLogicalName));

    // Save the image retrieved
    File.WriteAllBytes(
        path: "original_image.png",
        bytes: account.GetAttributeValue<byte[]>(imageColumnLogicalName));


    // Instantiate a new entity for update with new image
    Entity accountForUpdate = new("account") { 
        Attributes = {
            { "accountid", accountid },
            { imageColumnLogicalName , File.ReadAllBytes("new_image.png")}
        }
    };

    // Update the account
    service.Update(accountForUpdate);               
}

Hinweis

Wenn Sie die ColumnSet.AllColumns-Eigenschaft auf "true" festlegen, enthält die Abfrage keine Bildspalten. Aus Leistungsgründen müssen Sie explizit angeben, dass Sie Bilddaten abrufen möchten.

Weitere Informationen:

Legen Sie nur primäre Bilder für den Erstellungsvorgang fest.

Wenn Sie einen Datensatz erstellen, legen Sie nur den Wert der aktuellen primären Bildspalte fest. Wenn Sie versuchen, den Wert einer anderen Bildspalte festzulegen, wird diese Fehlermeldung angezeigt:

Name: CannotUploadNonPrimaryImageAttributeOnCreate
Code: 0x80090487
Zahl: -2146892665
Meldung: Non-primary image attribute <image column logical name> of entity <table logical name> is not allowed to upload during Create operation.

Weitere Informationen finden Sie unter "Primäre Bilder".

Nur Miniaturansichten abrufen

Die Bilddaten, auf die Sie über die Datensatzeigenschaften zugreifen, sind immer Bilder in Miniaturansichten. Um auf Bilder in voller Größe zugreifen zu können, müssen Sie sie herunterladen. Weitere Informationen finden Sie unter "Bilder herunterladen".

Bilder hochladen

Verwenden Sie zum Hochladen von Bildern dieselben APIs, die Sie zum Hochladen von Dateien verwenden. Weitere Informationen finden Sie unter "Dateien hochladen".

Bilder hochladen

Verwenden Sie zum Herunterladen von Bildern die gleichen APIs, die Sie zum Herunterladen von Dateien verwenden. Beachten Sie die folgenden Unterschiede.

Verwenden Sie Dataverse-Nachrichten, um Bilder herunterzuladen

Wenn Sie die InitializeFileBlocksDownload- und DownloadBlock-Nachrichten verwenden, laden Sie das Bild immer in voller Größe herunter, wenn die Bildspalte es unterstützt. Sie können das Miniaturansichtsbild nicht mit dieser Methode herunterladen. Weitere Informationen finden Sie unter Verwenden von Dataverse-Nachrichten zum Herunterladen einer Datei.

Wenn die Bildspalte keine Bilder in voller Größe unterstützt oder wenn die ImageAttributeMetadata.CanStoreFullImage-Eigenschaft beim Hochladen des Bilds falsch ist, wird der folgende Fehler zurückgegeben:

Name: ObjectDoesNotExist
Code: 0x80040217
Zahl: -2147220969
Meldung: No FileAttachment records found for imagedescriptorId: <guid> for image attribute: <image column logical name> of <entity logical name> record with id <guid>.

Verwenden Sie die Web-API, um Bilder herunterzuladen

Wenn Sie Bilder mithilfe der Web-API herunterladen, ohne die Dataverse-Nachrichten zu verwenden, laden Sie das Miniaturbild standardmäßig herunter. Um das Bild in voller Größe herunterzuladen, fügen Sie diesen Parameter an die URL an: ?size=full.

Wenn die Bildspalte keine Bilder in voller Größe unterstützt oder wenn die ImageAttributeMetadata.CanStoreFullImage-Eigenschaft beim Hochladen des Bilds falsch ist, wird die Antwort zurückgegeben 204 No Content.

Weitere Informationen finden Sie unter "Dateien herunterladen".

Bilder löschen

Sie können Bilder löschen, indem Sie den Bildspaltenwert für den Datensatz wie für jede andere Eigenschaft auf Null setzen.

Legen Sie den Wert des Image-Attributs auf NULL fest, und aktualisieren Sie die Entität. Weitere Informationen finden Sie unter Grundlegende Aktualisierung.

Siehe auch

Dateien und Bilder – Übersicht
Mithilfe von Code mit Bildspaltendefinitionen arbeiten
Beispiel: Bildoperationen mit dem Dataverse SDK für .NET
Beispiel: Bildvorgänge über die Dataverse-API
Dateispaltendaten verwenden

  • Zuletzt aktualisiert um