Colonnes de fichier

Une colonne de fichier est utilisée pour stocker les données de fichier jusqu’à une taille maximale spécifiée. Un tableau personnalisé ou personnalisable peut avoir zéro ou plusieurs colonnes de fichier plus une collection de notes (annotations) avec zéro à une pièce jointe dans chaque note. SchemaName de la colonne de fichier est EntityFile.

Notes

Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.

API Web (REST) API .NET (SOAP)
FileAttributeMetadata FileAttributeMetadata

Pour plus d’informations sur les types de fichiers qui ne sont pas autorisés, voir Onglet Général Paramètres système sous le paramètre Définir les extensions de fichier bloquées pour les pièces jointes.

Important

Certaines restrictions s’appliquent lors de l’utilisation des données de type Fichier et Image améliorée de Microsoft Dataverse. Si les clés gérées par le client (CMK) sont activées sur le locataire, les types de données IoT ne sont pas disponibles pour les organisations du locataire. Les solutions qui contiennent des types de données exclus ne s’installeront pas. Les clients doivent désactiver les clés gérées par eux afin de pouvoir utiliser ces types de données.

Toutes les organisations CMK à partir de la version 9.2.21052.00103 peuvent prendre en charge l’utilisation des types de données d’image et de fichier Dataverse. Les fichiers au sein des organisations CMK sont limités à une taille maximale de 128 Mo par fichier. Tous les fichiers et images des organisations CMK seront stockés dans le stockage relationnel Dataverse, au lieu du Stockage Blob Dataverse. Autres limitations :

  • Les téléchargements SAS de délégation d’utilisateurs ne sont pas pris en charge
  • Les chargements et téléchargements en bloc sont limités à un seul bloc

Les colonnes de fichiers sont prises en charge dansSdkClientVersion 9.0.45.329 ou supérieur et API web version 9.1 ou supérieure.

Colonnes de soutien

Lorsqu’une colonne de fichier est ajoutée à une table, des colonnes supplémentaires sont créées pour la prendre en charge.

Colonne MaxValue

Cette valeur représente la taille maximale (en kilo-octets) des données de fichier que la colonne peut contenir. Définissez cette valeur sur la plus petite taille de données accessible appropriée pour cette application spécifique. Consultez la propriété MaxSizeInKB pour connaître la limite de la taille autorisée et la valeur par défaut.

Notes

MaxValue est définie lorsque la colonne File est ajoutée à une table. Cette propriété ne peut pas être modifiée une fois qu’elle est définie.

Récupérer les données fichier

Pour récupérer les données de la colonne de fichier, utilisez les API suivantes.

API Web (REST) API .NET (SOAP)
aucun(e) InitializeFileBlocksDownloadRequest,
InitializeAttachmentBlocksDownloadRequest,
InitializeAnnotationBlocksDownloadRequest
GET /api/data/v9.1/<entity-type(id)>/<file-attribute-name>/$value DownloadBlockRequest

Les transferts des données fichier depuis les points de terminaison du service Web sont limités à un volume maximum de données de 16 Mo dans un appel de service unique. Les données fichier supérieures à ce volume doivent être réparties en blocs de données de 4 Mo maximum où chaque bloc est reçu dans un appel d’API distinct jusqu’à ce que toutes les données fichier aient été reçues. Il en va de votre responsabilité de joindre les blocs de données chargés pour former le fichier de données complet en associant les blocs de données dans la même séquence que celle où les blocs ont été reçus.

Des messages tels queRetrieveRequest etRetrieveMultipleRequest ne peut pas être utilisé pour télécharger des données de colonne de fichier.

Exemple : chargement REST avec segmentation

Demande

GET [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute/$value
Headers:
Range: bytes=0-1023/8192

Response

206 Partial Content

Body:
byte[]

Response Headers:
Content-Disposition: attachment; filename="sample.txt"
x-ms-file-name: "sample.txt"
x-ms-file-size: 8192
Location: api/data/v9.1/accounts(id)/myfileattribute?FileContinuationToken

La segmentation sera décidée selon l’existence de l’en-tête Range dans la requête. Le format de valeur d’en-tête Plage est : startByte-endByte/total bytes. Le fichier complet sera chargé (jusqu’à 16 Mo) dans une requête si aucun en-tête Range n’est inclus. Pour la segmentation, l’en-tête de réponse Location contient le paramètre d’activation de la requête FileContinuationToken. Utilisez la valeur d’en-tête d’emplacement fournie dans la requête GET suivante pour récupérer le bloc de données suivant dans la séquence.

Exemple : code C# .NET pour chargement avec segmentation

static async Task ChunkedDownloadAsync(
            Uri urlPrefix,
            string customEntitySetName,
            string entityId,
            string entityFileOrAttributeAttributeLogicalName,
            string fileRootPath,
            string downloadFileName,
            string token)
        {
            var url = new Uri(urlPrefix, $"{customEntitySetName}({entityId})/{entityFileOrAttributeAttributeLogicalName}/$value?size=full");
            var increment = 4194304;
            var from = 0;
            var fileSize = 0;
            byte[] downloaded = null;
            do
            {
                using (var request = new HttpRequestMessage(HttpMethod.Get, url))
                {
                    request.Headers.Range = new System.Net.Http.Headers.RangeHeaderValue(from, from + increment - 1);
                    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
                    using (var response = await Client.SendAsync(request))
                    {
                        if (downloaded == null)
                        {
                            fileSize = int.Parse(response.Headers.GetValues("x-ms-file-size").First());
                            downloaded = new byte[fileSize];
                        }

                        var responseContent = await response.Content.ReadAsByteArrayAsync();
                        responseContent.CopyTo(downloaded, from);
                    }
                }

                from += increment;
            } while (from < fileSize);

            await File.WriteAllBytesAsync(Path.Combine(fileRootPath, downloadFileName), downloaded);
        }

Charger les données de fichier

Pour télécharger les données de la colonne de fichier, utilisez les API suivantes.

API Web (REST) API .NET (SOAP)
aucun(e) InitializeFileBlocksUploadRequest,
InitializeAttachmentBlocksUploadRequest,
InitializeAnnotationBlocksUploadRequest
PATCH /api/data/v9.1/<entity-type(id)>/<file-attribute-name> UploadBlockRequest
aucun(e) CommitFileBlocksUploadRequest,
CommitAttachmentBlocksUploadRequest,
CommitAnnotationBlocksUploadRequest

Les fichiers peuvent être chargés en totalité jusqu’à la taille maximale configurée, ou bien par segments.

Notes

À compter de la date de publication de cet article, la restriction d’utilisation du chargement fragmenté pour les fichiers d’une taille supérieure à 16 Mo a été supprimée. Les API de segmentation continueront d’être disponibles pour maintenir la rétrocompatibilité avec les solutions existantes.

Exemple : code .NET C# pour le chargement de fichier complet

static async Task FullFileUploadAsync(
            Uri urlPrefix,
            string customEntitySetName,
            string entityId,
            string entityFileOrAttributeAttributeLogicalName,
            string fileRootPath,
            string uploadFileName,
            string accessToken)
        {
            var filePath = Path.Combine(fileRootPath, uploadFileName);
            var fileStream = File.OpenRead(filePath);
            var url = new Uri(urlPrefix, $"{customEntitySetName}({entityId})/{entityFileOrAttributeAttributeLogicalName}");

            using (var request = new HttpRequestMessage(new HttpMethod("PATCH"), url))
            {
                request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
                                request.Content = new StreamContent(fileStream);
                request.Content.Headers.Add("Content-Type", "application/octet-stream");
                request.Content.Headers.Add("x-ms-file-name", uploadFileName);
                                
                using (var response = await Client.SendAsync(request))
                {
                    response.EnsureSuccessStatusCode();
                }
            }
        }

Voici la méthode héritée de chargement d’un fichier de données d’une taille de 16 Mo ou plus en divisant le fichier en blocs de données de 4 Mo ou moins. Une fois l’ensemble des blocs de données chargés et une demande de validation envoyée, le service Web associera automatiquement les blocs, dans la même séquence où les blocs de données ont été chargés, dans un seul fichier de données dans Azure Blob Storage.

Des messages tels queCreateRequest etUpdateRequest ne peut pas être utilisé pour télécharger des données de colonne de fichier.

Exemple : Chargement REST avec segmentation (première demande)

Demande

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute 

Headers: 
x-ms-transfer-mode: chunked 
x-ms-file-name: sample.png

Demande (forme alternative)

Cette forme de la demande utilise un paramètre de chaîne de requête et prend en charge les noms de fichiers en langage non ASCII. Si le nom de fichier est spécifié à la fois dans l’en-tête et en tant que paramètre de chaîne de requête, la valeur d’en-tête a la priorité.

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute?x-ms-file-name=测试.txt

Headers: 
x-ms-transfer-mode: chunked

Response

200 OK 

Response Headers: 
x-ms-chunk-size: 4096 
Accept-Ranges: bytes 
Location: api/data/v9.1/accounts(id)/myfileattribute?FileContinuationToken 

Exemple : Chargement REST avec segmentation (demande suivante)

Demande

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute?FileContinuationToken 

Headers: 
Content-Range: bytes 0-4095/8192 
Content-Type: application/octet-stream
x-ms-file-name: sample.png

Body:
byte[]

Réponse

206 Partial Content

Exemple : code C# .NET pour chargement avec segmentation

static async Task ChunkedUploadAsync(
            Uri urlPrefix,
            string customEntitySetName,
            string entityId,
            string entityFileOrAttributeAttributeLogicalName,
            string fileRootPath,
            string uploadFileName,
            string accessToken)
        {
            var filePath = Path.Combine(fileRootPath, uploadFileName);
            var fileBytes = await File.ReadAllBytesAsync(filePath);
            var url = new Uri(urlPrefix, $"{customEntitySetName}({entityId})/{entityFileOrAttributeAttributeLogicalName}");

            var chunkSize = 0;
            using (var request = new HttpRequestMessage(HttpMethod.Patch, url))
            {
                request.Headers.Add("x-ms-transfer-mode", "chunked");
                request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
                request.Headers.Add("x-ms-file-name", uploadFileName);
                using (var response = await Client.SendAsync(request))
                {
                    response.EnsureSuccessStatusCode();
                    url = response.Headers.Location;
                    chunkSize = int.Parse(response.Headers.GetValues("x-ms-chunk-size").First());
                }
            }

            for (var offset = 0; offset < fileBytes.Length; offset += chunkSize)
            {
                var count = (offset + chunkSize) > fileBytes.Length ? fileBytes.Length % chunkSize : chunkSize;
                using (var content = new ByteArrayContent(fileBytes, offset, count))
                using (var request = new HttpRequestMessage(HttpMethod.Patch, url))
                {
                    content.Headers.Add("Content-Type", "application/octet-stream");
                    content.Headers.ContentRange = new System.Net.Http.Headers.ContentRangeHeaderValue(offset, offset + (count - 1), fileBytes.Length);
                    request.Headers.Add("x-ms-file-name", uploadFileName);
                    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
                    request.Content = content;
                    using (var response = await Client.SendAsync(request))
                    {
                        response.EnsureSuccessStatusCode();
                    }
                }
            }
        }

Supprimer des données fichier

Pour supprimer les données de colonne de fichier du stockage, utilisez les API suivantes.

API Web (REST) API .NET (SOAP)
DELETE /api/data/v9.1/<entity-type(id)>/<attribute-name> DeleteFileRequest

Voir aussi

Colonnes d’image

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).