Freigeben über


Bildspaltendaten verwenden

Sie können Bilddaten in Dataverse unter Verwendung von Bildspalten oder Dateispalten speichern. Sie können viele der APIs für Dateispalten mit Bildspalten verwenden. Bildspalten haben einige spezielle Verhaltensweisen und Einschränkungen, um die Anzeige von Bildern in Anwendungen zu unterstützen.

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. Während die API Dateien mit einer Größe von bis zu 10 GB verarbeiten kann, unterstützen Power Apps Client-Steuerelemente derzeit nur Dateien mit bis zu 128 MB. Wird die Größe von 128 MB überschritten, führt die Verwendung dieser Steuerelemente zu Fehlern beim Hoch- 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 unter Verwendung der Aktualisierung festlegen. 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 setzen und dann den Datensatz aktualisieren. Weitere Informationen: Bilder löschen Sie können Dateispaltendaten nur löschen, indem Sie die DeleteFile-Meldung verwenden oder eine DELETE-Anforderung an die spezifische 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 mit „Erstellen“ Bilddaten mit anderen Datensatzdaten festlegen. Weitere Informationen: Primäre Bilder Sie können Dateien nur einzeln in Dateispalteneigenschaften hochladen, nachdem der Datensatz erstellt wurde.
Mit Abrufen zurückgeben Sie können mit „Abrufen“ Bilder in Miniaturgröße mit anderen Datensatzdaten abrufen. Bei dem zurückgegebenen Wert handelt es sich um die Datei-ID. Weitere Informationen: Verhalten beim Abrufen
URL herunterladen 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 bei Dateispalten können Sie die maximale Größe der in einer Bildspalte gespeicherten Daten mithilfe der Eigenschaft MaxSizeInKb angeben. Die maximal zugelassene Größe beträgt jedoch 30 MB.

Wenn Sie versuchen, eine zu große Datei hochzuladen, erhalten Sie die folgende Fehlermeldung:

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

Sie können die folgenden Beispiele verwenden, 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 keinen dieser Typen hat, erhalten Sie die folgende Fehlermeldung:

Name: ProcessImageFailure
Code: 0x80072553
Nummer: -2147015341
Meldung: Error occured 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 ein Bildspaltenwert festgelegt wird, generiert Dataverse automatisch ein Bild in Miniaturbildgröße, das als Symbol in einer Anwendung verwendet werden kann.

Wenn die Bildspalte zum Speichern eines Bildes in voller Größe konfiguriert ist, kann eine Datei bis zum konfigurierten MaxSizeInKb gespeichert und separat von dem Bild in Miniaturbildgröße heruntergeladen werden. 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

Sie können die Bildattributkonfigurationstabelle (AttributeImageConfig) abfragen, um eine Liste von Bildspalten abzurufen, die Bilder in voller Größe unterstützen. Verwenden Sie dazu parententitylogicalname-, attributelogicalname- und canstorefullimage-Spaltenwerte.

Die statische PrintFullSizedImageColumns-Methode schreibt die Namen der Tabellen- und Bildspalten, die Bilder in voller Größe speichern können.

static void PrintFullSizedImageColumns(IOrganizationService service)
{
    QueryExpression query = new QueryExpression("attributeimageconfig")
    {
        ColumnSet = new ColumnSet("parententitylogicalname", "attributelogicalname"),
        Criteria = new FilterExpression(LogicalOperator.And)
        {
            Conditions =
            {
                new ConditionExpression(
                    attributeName: "canstorefullimage",
                    conditionOperator: ConditionOperator.Equal,
                    value: true)
            }
        }
    };

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

Output

account.sample_sampleimage

Sie können auch Schemadefinitionen abfragen, um Spalten zurückzugeben, bei denen die ImageAttributeMetadata.CanStoreFullImage-Eigenschaft auf „wahr“ steht. Weitere Informationen: Abfrageschemadefinitionen

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

Um ein Bild in Miniaturansicht zu erzeugen, schneidet Dataverse das Bild gemäß den folgenden Regeln auf eine quadratische Form zu und ändert seine Größe:

  • Bilder, bei denen mindestens eine Seite größer ist als 144 Pixel, werden zentriert auf 144x144 zugeschnitten.
  • Bilder, bei denen beide Seiten kleiner sind als 144 Pixel, werden quadratisch auf ihre kleinste Seite zugeschnitten.

Die folgende Tabelle enthält zwei Beispiele.

Vorher After
Bild vor Größenänderung

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

144x144
Kleineres Bild vor Größenänderung

91x130
Kleineres Bild nach Größenänderung

91x91

Primäre Bilder

Jede Tabelle kann mehrere Bildspalten haben, aber nur eine Bildspalte kann als primäres Bild festgelegt werden. Nur das primäre Bild kann mit einem Erstellungsvorgang festgelegt werden. Weitere Informationen: Nur primäre Bilder können zum Erstellen festgelegt werden

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 die auch die Entitätsbildkonfigurationstabelle (EntityImageConfig) abfragen, um zu bestimmen, welche Bildspalten das aktuelle primäre Bild darstellen, indem Sie die parententitylogicalname- und primaryimageattribute-Spaltenwerte verwenden.

Die statische PrintPrimaryImageColumns-Methode schreibt die Tabellen- und Bildspaltennamen aller 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 Type Namenskonvention 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 hilft, sicherzustellen, dass die neueste Version des Bilds heruntergeladen wird und der Client keine zwischengespeicherte Version verwendet, die zuvor abgerufen wurde.
URL string <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 URL zum Herunterladen eine relative URL im folgenden Format:

/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 anhängen, um eine URL zu erstellen, die zum Herunterladen der Bilddatei in Miniaturansicht verwendet werden kann. 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 zum Speichern von Bildern in voller Größe konfiguriert ist, können Sie &Full=true an die URL anhängen 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 in voller Größe konfiguriert ist, werden keine Daten zurückgegeben.

Verwenden Sie Bilddaten mit Aufzeichnungen

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

Die folgende statische RetrieveAndUpdateImageColumn-Methode ruft einen byte[]-Bildwert aus einer Spalte ab, speichert ihn lokal und lädt ein neues Bild hoch.

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

Bildspalten sind nicht eingeschlossen, wenn Sie die ColumnSet.AllColumns-Eigenschaft auf „wahr“ setzen. Aus Leistungsgründen müssen Sie explizit angeben, dass Sie Bilddaten abrufen möchten.

Weitere Informationen:

Nur primäre Bilder können zum Erstellen festgelegt werden

Wenn Sie einen Datensatz erstellen, können Sie nur den Wert der aktuellen primären Bildspalte festlegen. Wenn Sie versuchen, den Wert einer anderen Bildspalte festzulegen, erhalten Sie diesen Fehler:

Name: CannotUploadNonPrimaryImageAttributeOnCreate
Code: 0x80090487
Nummer: -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: Primäre Bilder

Es können nur Miniaturansichten abgerufen werden

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: Bilder herunterladen

Bilder hochladen

Verwenden Sie dieselben APIs, die Sie zum Hochladen von Dateien verwenden, um Bilder einzeln hochzuladen. Weitere Informationen: Dateien hochladen

Bilder hochladen

Verwenden Sie dieselben APIs, die Sie zum Herunterladen von Dateien verwenden, um Bilder herunterzuladen. Achten Sie aber auf die folgenden Unterschiede.

Dataverse-Nachrichten verwenden

Wenn Sie die InitializeFileBlocksDownload- und DownloadBlock-Meldungen verwenden, wird das Bild immer in voller Größe heruntergeladen, wenn die Bildspalte dies unterstützt. Mit dieser Methode können Sie das Bild als Miniaturansicht nicht herunterladen. Weitere Informationen: Dataverse-Nachrichten zum Herunterladen einer Datei verwenden

Wenn die Bildspalte keine Bilder in voller Größe unterstützt oder wenn die ImageAttributeMetadata.CanStoreFullImage-Eigenschaft auf „falsch“ gesetzt war, als das Bild hochgeladen wurde, wird der folgende Fehler zurückgegeben:

Name: ObjectDoesNotExist
Code: 0x80040217
Nummer: -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 von Web-API

Wenn Sie Bilder mit der Web-API herunterladen, ohne die Dataverse-Nachrichten zu verwenden, wird standardmäßig das Bild in Miniaturansicht heruntergeladen. Um das Bild in voller Größe herunterzuladen, müssen Sie diesen Parameter an die URL anhängen: ?size=full.

Wenn die Bildspalte keine Bilder in voller Größe unterstützt oder wenn die ImageAttributeMetadata.CanStoreFullImage-Eigenschaft auf „falsch“ gesetzt war, als das Bild hochgeladen wurde, gibt die Antwort 204 No Content zurück.

Weitere Informationen: 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.

Setzen Sie den Wert der Bildeigenschaft einfach auf Null und aktualisieren Sie die Entität. Weitere Informationen: Basisches Update

Siehe auch

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