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 |
|---|---|
300x428 |
144x144 |
91x130 |
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