Columnas de archivo

Artigo
07/06/2022
3 minutos de lectura

Una columna de archivo se utiliza para almacenar datos de archivo hasta un tamaño máximo especificado. Una tabla personalizada o personalizable puede tener cero o más columnas de archivo más una colección de notas (anotaciones) con cero o un archivo adjunto en cada nota. SchemaName de la columna del archivo es EntityFile, LogicalName es entityfile.

Nota

¿No está seguro de entidad frente a tabla? Vea Desarrolladores: comprender la terminología en Microsoft Dataverse.

API Web	SDK para .NET
FileAttributeMetadata	FileAttributeMetadata

Para obtener información sobre los tipos de archivos que no están permitidos, consulte Pestaña General Configuración del sistema en la configuración Definir las extensiones de archivo bloqueadas para datos adjuntos.

Importante

Se aplican algunas restricciones al usar el archivo y los tipos de datos de imagen mejorados de Microsoft Dataverse. Si las claves administradas por el cliente (CMK) están habilitadas en el inquilino, los tipos de datos de IoT no están disponibles para las organizaciones del inquilino. Las soluciones que contienen tipos de datos excluidos no se instalan. Los clientes deben cancelar la suscripción a CMK para hacer uso de estos tipos de datos.

Todas las organizaciones de CMK a partir de la versión: 9.2.21052.00103 pueden admitir el uso de tipos de datos de archivo e imagen de Dataverse. Los archivos dentro de las organizaciones CMK están limitados a un tamaño máximo de 128 MB por archivo. Todos los archivos e imágenes dentro de las organizaciones de CMK se almacenarán en el almacenamiento relacional de Dataverse, en lugar del almacenamiento de blobs de archivos de Dataverse. Otras limitaciones:

Las descargas SAS de delegación de usuarios no son compatibles
Las cargas y descargas fragmentadas están limitadas a una sola parte

Las columnas de archivo se admiten en SdkClientVersion 9.0.45.329 o superior y Web API, versión 9.1 o superior. Las columnas de archivo son compatibles con los portales de Power Apps solo en la tabla de notas (anotación).

Columnas de apoyo

Cuando se agrega una columna de archivo a una tabla, se crean algunas columnas adicionales para respaldarla.

Columna MaxValue

La columna MaxValue representa el tamaño máximo (en kilobytes) de los datos del archivo que la columna puede contener. Establezca este valor en el tamaño de datos más pequeño que pueda usar para su aplicación específica. Vea MaxSizeInKB property para el límite de tamaño permisible y el valor predeterminado.

Nota

MaxValue se establece cuando la columna Archivo se agrega a una tabla. Esto no se puede cambiar después de establecerse.

Recuperar datos de archivo

No puede usar los mensajes Retrieve y RetrieveMultiple para descargar los datos del archivo.

Para recuperar datos de columnas de archivos, utilice las siguientes API.

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

Las transferencias de datos de archivo desde extremos de servicio web están limitadas a un máximo de 16 MB de datos en una sola llamada de servicio. Los datos de archivo más grandes que la cantidad se deben dividir en bloques de datos de 4 MB o más pequeños (fragmentos) donde cada bloque se recibe en una llamada API independiente hasta que se hayan recibido todos los datos de archivo. Es responsabilidad suya unir los bloques de datos descargados para formar el archivo de datos completo combinando los bloques de datos en la misma secuencia en que se recibieron.

Solicitud

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

Respuesta

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 fragmentación se decide en función de la existencia del encabezado Range en la solicitud. El formato del valor de encabezado Range es: startByte-endByte/total bytes. El archivo completo se descargará (hasta 16 MB) en una solicitud si no hay encabezado Range incluido. Para la fragmentación, el encabezado de respuesta Location contiene el parámetro consultable FileContinuationToken. Use el valor de encabezado de ubicación que se proporciona en la solicitud GET siguiente para recuperar el siguiente bloque de datos en la secuencia.

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

Cargar archivo de datos

No puede usar los mensajes Create y Update para cargar los datos del archivo.

Para cargar datos de columnas de archivos, utilice las siguientes API.

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

Puede cargar archivos completos, hasta el tamaño máximo configurado o en fragmentos.

Nota

A partir de la fecha de publicación de este artículo, se eliminó la restricción de usar la carga fragmentada para archivos de más de 16 MB. Las API de fragmentación seguirán estando disponibles para mantener la compatibilidad con las soluciones existentes.

Ejemplo: código .NET C# para la carga completa de archivos mediante la API web

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();
        }
    }
}

Ejemplo: Cargar con fragmentación

El siguiente es el método heredado para cargar un archivo de datos de 16 MB o más dividiendo el archivo en bloques de datos de 4 MB o menos. Cuando el conjunto completo de bloques de datos se ha cargado y se ha enviado una solicitud de confirmación, el servicio web combinará automáticamente los bloques, en la misma secuencia que los bloques de datos se cargaron, en un archivo de datos único en Azure Blob Storage.

API web
SDK para .NET

Primera solicitud

Solicitud

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

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

Solicitud (formulario alternativo)

Esta forma de solicitud utiliza un parámetro de cadena de consulta y admite nombres de archivos de idiomas que no son ASCII. Si el nombre del archivo se especifica en el encabezado y como un parámetro de cadena de consulta, el valor del encabezado tiene prioridad.

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

Headers: 
x-ms-transfer-mode: chunked

Respuesta

200 OK 

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

Siguiente solicitud

Solicitud

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[]

Respuesta

206 Partial Content

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();
            }
        }
    }
}

Eliminar datos de archivo

Para eliminar los datos de la columna de archivo del almacenamiento, utilice las siguientes API.

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

Vea también

Columnas imagen

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Columnas de archivo

Columnas de apoyo

Columna MaxValue

Recuperar datos de archivo

Ejemplo: Descargar con fragmentación

Cargar archivo de datos

Ejemplo: código .NET C# para la carga completa de archivos mediante la API web

Ejemplo: Cargar con fragmentación

Primera solicitud

Siguiente solicitud

Eliminar datos de archivo

Vea también

Comentarios