Operaciones básicas con archivos y carpetas¶
Resumen¶
Esta página ofrece, para quienes desarrollan clientes, una visión general de las operaciones WebDAV con archivos y carpetas: la autenticación y el endpoint de los recursos compartidos públicos, cómo probar solicitudes, las propiedades que se pueden solicitar, las operaciones para listar, descargar, subir, crear, eliminar, mover y copiar, los favoritos y las cabeceras especiales de solicitud y de respuesta.
Fuente: documentación de Nextcloud, «developer_manual/client_apis/WebDAV/basic», versión 3ad9158, licencia CC BY 3.0; traducida y adaptada para APS Conecta Gestión.
Este documento ofrece una visión general rápida de las operaciones WebDAV que admite APS Conecta Gestión. Para que resulte legible, no entra en muchos detalles de cada operación; se puede encontrar más información sobre cada operación en el RFC correspondiente, cuando corresponda.
Fundamentos de WebDAV¶
La URL base de todas las operaciones WebDAV (autenticadas) de una instancia de APS Conecta Gestión es /remote.php/dav. Para las operaciones con archivos, esto suele
significar rutas bajo /remote.php/dav/files/{user}/....
Todas las solicitudes deben proporcionar información de autenticación, ya sea como una cabecera de autenticación básica o pasando un conjunto de cookies de sesión válidas.
Si la instalación de APS Conecta Gestión usa un proveedor de autenticación externo (como un servidor OIDC) o impone políticas como la 2FA, puede ser necesario crear una contraseña de aplicación para los clientes y scripts WebDAV. Para ello, ir a los ajustes personales de seguridad y crear una. Esta proporcionará un nombre de usuario y una contraseña que se pueden usar en la cabecera Basic Auth.
Recursos compartidos públicos¶
El endpoint /remote.php/dav solo permite el acceso autenticado a los recursos WebDAV;
para los archivos compartidos mediante enlaces públicos se ofrece otro endpoint, que no requiere autenticación.
La URL base de los enlaces públicos compartidos es /public.php/dav, en concreto para archivos: /public.php/dav/files/{share_token}.
Si el recurso compartido tiene una contraseña, hay que enviar una cabecera de autenticación básica con anonymous como nombre de usuario y la contraseña del recurso compartido como contraseña.
Nota
Este endpoint para recursos compartidos públicos está disponible desde APS Conecta Gestión 29.
Advertencia
En las solicitudes que no son GET (p. ej., PROPFIND, PUT) a /public.php/dav, la solicitud debe incluir la cabecera
X-Requested-With: XMLHttpRequest, salvo que el uso compartido saliente de servidor a servidor esté habilitado en la instancia.
Sin esta cabecera, el servidor rechazará la solicitud con una respuesta 401 Not Authenticated.
Probar solicitudes¶
Con curl¶
Todas las solicitudes WebDAV se pueden probar fácilmente con curl, especificando el método de la solicitud (GET, PROPFIND, PUT, ...) y proporcionando un cuerpo de solicitud cuando sea necesario.
Por ejemplo, se puede realizar una solicitud PROPFIND para encontrar los archivos de una carpeta con:
curl 'https://cloud.example.com/remote.php/dav/files/username/folder' \
--user username:password \
--request PROPFIND \
--data '<?xml version="1.0" encoding="UTF-8"?>
<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
<d:prop>
<d:getlastmodified/>
<d:getcontentlength/>
<d:getcontenttype/>
<oc:permissions/>
<d:resourcetype/>
<d:getetag/>
</d:prop>
</d:propfind>'
Realizar solicitudes en JavaScript¶
Este es un ejemplo de código JavaScript para empezar:
import { createClient } from 'webdav'
import { generateRemoteUrl } from '@nextcloud/router'
import { getCurrentUser } from '@nextcloud/auth'
const client = createClient(generateRemoteUrl('dav'))
const response = await client.getDirectoryContents(`/files/${getCurrentUser()?.uid}/folder`, {
details: true,
data: `<?xml version="1.0" encoding="UTF-8"?>
<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
<d:prop>
<d:getlastmodified/>
<d:getcontentlength/>
<d:getcontenttype/>
<oc:permissions/>
<d:resourcetype/>
<d:getetag/>
</d:prop>
</d:propfind>`,
})
Referencia rápida de métodos y cabeceras¶
La tabla siguiente resume los métodos WebDAV habituales que usa APS Conecta Gestión y las cabeceras más relevantes.
Método |
Endpoint típico |
Cabeceras de solicitud importantes |
Notas |
|---|---|---|---|
PROPFIND |
|
|
Sin |
REPORT |
|
(ninguna obligatoria) |
Se usa para consultas filtradas, como los favoritos. |
GET (archivo) |
|
(ninguna obligatoria) |
Descarga el contenido del archivo. |
GET (directorio) |
|
|
Extensión de APS Conecta Gestión para descargar una carpeta como archivo comprimido. |
PUT |
|
Opcionales: |
Sube o sobrescribe el contenido del archivo. |
MKCOL |
|
(ninguna obligatoria) |
Crea una carpeta. |
DELETE |
|
(ninguna obligatoria) |
La eliminación de una carpeta es recursiva. |
MOVE |
|
|
Opcional: |
COPY |
|
|
Opcional: |
PROPPATCH |
|
(ninguna obligatoria) |
Establece propiedades como |
Solicitar propiedades¶
De forma predeterminada, una solicitud PROPFIND solo devuelve un pequeño número de propiedades de cada archivo: la fecha de última modificación, el tamaño del archivo, si es una carpeta, el etag y el tipo MIME.
Se pueden solicitar propiedades adicionales enviando con la solicitud PROPFIND un cuerpo que liste todas las propiedades solicitadas.
Si una propiedad no se admite para un recurso, el servidor la indicará como no encontrada en la respuesta multi-status para esa propiedad.
<?xml version="1.0"?>
<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
<d:prop>
<d:getlastmodified />
<d:getetag />
<d:getcontenttype />
<d:resourcetype />
<oc:fileid />
<oc:permissions />
<oc:size />
<d:getcontentlength />
<nc:has-preview />
<oc:favorite />
<oc:comments-unread />
<oc:owner-display-name />
<oc:share-types />
<nc:contained-folder-count />
<nc:contained-file-count />
</d:prop>
</d:propfind>
Una nota sobre los URI de espacio de nombres¶
Al construir el cuerpo de la solicitud DAV, se solicitan propiedades que están disponibles bajo URI de espacio de nombres específicos.
Es habitual declarar prefijos para esos espacios de nombres en el elemento d:propfind del cuerpo.
Esta es la lista de espacios de nombres disponibles:
URI |
Prefijo |
|---|---|
DAV: |
d |
oc |
|
nc |
|
ocs |
|
ocm |
Y así es como debería verse en la solicitud DAV:
<?xml version="1.0"?>
<d:propfind
xmlns:d="DAV:"
xmlns:oc="http://owncloud.org/ns"
xmlns:nc="http://nextcloud.org/ns"
xmlns:ocs="http://open-collaboration-services.org/ns"
xmlns:ocm="http://open-cloud-mesh.org/ns">
...
</d:propfind>
Propiedades admitidas¶
Nota
Las propiedades del espacio de nombres d: son propiedades WebDAV estándar (RFC 4918).
La mayoría de las propiedades de oc:, nc:, ocs: y ocm: son extensiones propias de APS Conecta Gestión.
Propiedad |
Descripción |
Ejemplo |
|---|---|---|
<d:creationdate /> |
La fecha de creación del nodo. |
|
<d:getlastmodified /> |
La hora de la última modificación. |
|
<d:getetag /> |
El etag del archivo. |
|
<d:getcontenttype /> |
El tipo MIME del archivo. |
|
<d:resourcetype /> |
Especifica la naturaleza del recurso. |
|
<d:getcontentlength /> |
El tamaño en bytes, si es un archivo. |
|
<d:getcontentlanguage /> |
El idioma del contenido. |
|
<d:displayname /> |
Un nombre adecuado para mostrar. |
|
<d:lockdiscovery /> |
Endpoint ficticio para la compatibilidad con WebDAV de clase 2. Debería devolver la lista de bloqueos, pero siempre devuelve una respuesta vacía. |
|
<d:quota-available-bytes /> |
Cantidad de bytes disponibles en la carpeta. |
|
<d:quota-used-bytes /> |
Cantidad de bytes usados en la carpeta. |
|
<d:supportedlock /> |
Endpoint ficticio para la compatibilidad con WebDAV de clase 2. Siempre proporciona las mismas capacidades de bloqueo. |
<d:lockentry>
<d:lockscope><d:exclusive /></d:lockscope>
<d:locktype><d:write /></d:locktype></d:lockentry>
</d:lockentry>
<d:lockentry>
<d:lockscope><d:shared /></d:lockscope>
<d:locktype><d:write /></d:locktype></d:lockentry>
</d:lockentry>
|
<oc:id /> |
El fileid, con el ID de la instancia como espacio de nombres. Único globalmente. |
|
<oc:fileid /> |
El ID único del archivo dentro de la instancia. |
|
<oc:downloadURL /> |
Una URL para descargar el archivo directamente desde un almacenamiento. Ningún almacenamiento lo implementa todavía. |
|
<oc:permissions /> |
Los permisos que tiene el usuario sobre el archivo o la carpeta. El valor es una cadena que contiene letras para todos los permisos disponibles. En los recursos compartidos públicos, |
|
<nc:creation_time /> |
Igual que |
|
<nc:mount-type /> |
El tipo de montaje. |
|
<nc:hide-download /> |
En los recursos compartidos, indica si se debe ocultar o no cualquier acción de descarga. |
|
<nc:is-encrypted /> |
Si la carpeta está cifrada de extremo a extremo. |
|
<nc:is-mount-root /> |
Es una propiedad especial que se usa para determinar si un nodo es una raíz de montaje o no, p. ej., una carpeta compartida. Si lo es, el nodo solo se puede dejar de compartir, no eliminar. |
|
<oc:tags /> |
Lista de etiquetas especificadas por el usuario. |
|
<oc:favorite /> |
El estado de favorito. |
|
<oc:comments-href /> |
El endpoint DAV para obtener los comentarios. |
|
<oc:comments-count /> |
El número de comentarios. |
|
<oc:comments-unread /> |
El número de comentarios no leídos. |
|
<oc:owner-id /> |
El ID de usuario del propietario de un archivo compartido. |
|
<oc:owner-display-name /> |
El nombre visible del propietario de un archivo compartido. |
|
<oc:share-types /> |
Array XML de tipos de recurso compartido. |
|
<ocs:share-permissions /> |
Los permisos que tiene el usuario sobre el recurso compartido. |
|
<ocm:share-permissions /> |
Los permisos que tiene el usuario sobre el recurso compartido, como array JSON. |
|
<nc:share-attributes /> |
Atributos establecidos por el usuario, como array JSON. |
|
<nc:sharees /> |
La lista de destinatarios del recurso compartido. |
<nc:sharee>
<nc:id>alice</nc:id>
<nc:display-name>Alice</nc:display-name>
<nc:type>0</nc:type>
</nc:sharee>
|
<oc:checksums /> |
Un array de sumas de comprobación almacenadas en la BD por otros clientes. Los algoritmos usados actualmente son: |
|
<nc:has-preview /> |
Si hay una vista previa disponible del archivo. |
|
<nc:hidden /> |
Define si un archivo debe ocultarse. Actualmente solo se usa para las fotos en vivo. |
|
<oc:size /> |
A diferencia de |
|
<nc:rich-workspace-file /> |
El ID del archivo del espacio de trabajo. |
3456 |
<nc:rich-workspace /> |
El contenido del archivo del espacio de trabajo. |
|
<nc:upload_time /> |
Fecha en que se subió este archivo. |
|
<nc:note /> |
Nota del recurso compartido. |
|
<nc:contained-folder-count /> |
El número de carpetas contenidas directamente en la carpeta (no de forma recursiva). |
|
<nc:contained-file-count /> |
El número de archivos contenidos directamente en la carpeta (no de forma recursiva). |
|
<nc:data-fingerprint /> |
Lo usan los clientes para averiguar si se ha restaurado una copia de seguridad. |
|
<nc:acl-enabled> |
Si la ACL está habilitada para esta carpeta de grupo. |
|
<nc:acl-can-manage> |
Si el usuario actual puede gestionar la ACL. |
|
<nc:acl-list> |
Array de reglas de ACL. |
<nc:acl>
<nc:acl-mapping-type>group</nc:acl-mapping-type>
<nc:acl-mapping-id>admin</nc:acl-mapping-id>
<nc:acl-mapping-display-name>admin</nc:acl-mapping-display-name>
<nc:acl-mask>20</nc:acl-mask>
<nc:acl-permissions>15</nc:acl-permissions>
</nc:acl>
|
<nc:inherited-acl-list> |
Array de reglas de ACL de las carpetas superiores |
Ver <nc:acl-list> |
<nc:group-folder-id> |
ID numérico de esa carpeta de grupo. |
|
<nc:lock> |
Si el archivo está bloqueado. |
|
<nc:lock-owner-type> |
Tipo del propietario del bloqueo. |
|
<nc:lock-owner> |
ID de usuario del propietario del bloqueo. |
|
<nc:lock-owner-displayname> |
Nombre visible del propietario del bloqueo. |
|
<nc:lock-owner-editor> |
ID de la app de un bloqueo que pertenece a una app. |
|
<nc:lock-time> |
Fecha en que se creó el bloqueo, como marca de tiempo. |
|
<nc:lock-timeout> |
TTL del bloqueo en segundos, a partir de la hora de creación. |
|
<nc:lock-token> |
El token del bloqueo. |
|
<nc:reminder-due-date> |
La fecha de vencimiento del recordatorio, como cadena con formato ISO 8601. |
|
<nc:version-label /> |
La etiqueta establecida por el usuario para un archivo. |
|
<nc:version-author /> |
El ID del autor de una versión concreta de un archivo. |
|
<nc:is-federated /> |
Si el nodo procede de un recurso compartido federado (de servidor a servidor). |
|
<nc:metadata_etag /> |
Un etag que cubre los metadatos del archivo. Cambia cuando se actualizan los metadatos (no el contenido). |
|
<nc:download-url-expiration /> |
Fecha y hora de caducidad de una URL de descarga directa (si se ha generado una). |
Nota
Las propiedades con el prefijo nc:metadata- (p. ej., nc:metadata-blurhash) son propiedades de metadatos dinámicas, registradas por las apps.
No se enumeran aquí una por una, ya que dependen de las apps que estén habilitadas.
Se pueden solicitar mediante PROPFIND como cualquier otra propiedad.
Listar carpetas (rfc4918)¶
El contenido de una carpeta se puede listar enviando una solicitud PROPFIND a la carpeta.
PROPFIND remote.php/dav/files/user/path/to/folder
Obtener las propiedades solo de la carpeta¶
Se pueden solicitar las propiedades de una carpeta sin obtener también su contenido añadiendo a la solicitud una cabecera Depth: 0.
Descargar archivos¶
Nota
En los archivos compartidos, esto solo funciona si quien los compartió no denegó el permiso de descarga.
Un archivo se puede descargar enviando una solicitud GET a la URL WebDAV del archivo.
GET remote.php/dav/files/user/path/to/file
Descargar carpetas¶
Nota
El método GET no está definido por el estándar WebDAV; es una extensión de WebDAV propia de APS Conecta Gestión.
Nota
En las carpetas compartidas, esto solo funciona si quien las compartió no denegó el permiso de descarga.
Una carpeta se puede descargar como archivo comprimido enviando una solicitud GET a la URL WebDAV de la carpeta.
La cabecera Accept debe estar establecida y contener el tipo MIME de los archivos ZIP (application/zip) o de los archivos tar (application/x-tar).
GET remote.php/dav/files/user/path/to/folder
Accept: application/zip
Opcionalmente, es posible incluir en el archivo comprimido solo algunos archivos de la carpeta, indicándolos con la cabecera personalizada X-NC-Files:
GET remote.php/dav/files/user/path/to/folder
Accept: application/zip
X-NC-Files: document.txt
X-NC-Files: image.png
Como con los enlaces HTML no es posible establecer cabeceras, también se pueden proporcionar ambas opciones como parámetros de consulta.
En ese caso, el valor de la cabecera Accept debe pasarse como el parámetro de consulta accept.
Se aceptan tanto los tipos MIME completos (application/zip, application/x-tar) como los valores abreviados (zip, tar).
La lista opcional de archivos se puede proporcionar como un array codificado en JSON mediante el parámetro de consulta files.
GET remote.php/dav/files/user/path/to/folder?accept=zip&files=["image.png","document.txt"]
Al usar parámetros de consulta, asegurarse de que los valores estén codificados como URL. En particular, files debe ser un array JSON codificado como URL.
Subir archivos¶
Un archivo se puede subir enviando una solicitud PUT al archivo, con el contenido sin procesar del archivo como cuerpo de la solicitud.
PUT remote.php/dav/files/user/path/to/file
La solicitud sobrescribirá cualquier archivo existente.
Crear carpetas (rfc4918)¶
Una carpeta se puede crear enviando una solicitud MKCOL a la carpeta.
MKCOL remote.php/dav/files/user/path/to/new/folder
Eliminar archivos y carpetas (rfc4918)¶
Un archivo o una carpeta se puede eliminar enviando una solicitud DELETE al archivo o a la carpeta.
DELETE remote.php/dav/files/user/path/to/file
Al eliminar una carpeta, su contenido se eliminará de forma recursiva.
Mover archivos y carpetas (rfc4918)¶
Un archivo o una carpeta se puede mover enviando una solicitud MOVE al archivo o a la carpeta y especificando el destino como URL completa en la cabecera Destination.
MOVE remote.php/dav/files/user/path/to/file
Destination: https://cloud.example/remote.php/dav/files/user/new/location
El comportamiento de sobrescritura del movimiento se puede controlar estableciendo la cabecera Overwrite en T o F para habilitar o deshabilitar la sobrescritura, respectivamente.
Copiar archivos y carpetas (rfc4918)¶
Un archivo o una carpeta se puede copiar enviando una solicitud COPY al archivo o a la carpeta y especificando el destino como URL completa en la cabecera Destination.
COPY remote.php/dav/files/user/path/to/file
Destination: https://cloud.example/remote.php/dav/files/user/new/location
El comportamiento de sobrescritura de la copia se puede controlar estableciendo la cabecera Overwrite en T o F para habilitar o deshabilitar la sobrescritura, respectivamente.
Marcar favoritos¶
Un archivo o una carpeta se puede marcar como favorito enviando una solicitud PROPPATCH al archivo o a la carpeta y estableciendo la propiedad oc:favorite.
PROPPATCH remote.php/dav/files/user/path/to/file
<?xml version="1.0"?>
<d:propertyupdate xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
<d:set>
<d:prop>
<oc:favorite>1</oc:favorite>
</d:prop>
</d:set>
</d:propertyupdate>
Establecer la propiedad oc:favorite en 1 marca un archivo como favorito; establecerla en 0 lo desmarca como favorito.
Listar favoritos¶
Los favoritos de un usuario se pueden obtener enviando una solicitud REPORT y especificando oc:favorite como filtro.
REPORT remote.php/dav/files/user/path/to/folder
<?xml version="1.0"?>
<oc:filter-files xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
<oc:filter-rules>
<oc:favorite>1</oc:favorite>
</oc:filter-rules>
</oc:filter-files>
Las propiedades de los archivos se pueden solicitar añadiendo a la solicitud un elemento <d:prop/> que liste las propiedades solicitadas, del mismo modo que se haría en una solicitud PROPFIND.
Al listar favoritos, la solicitud encuentra todos los favoritos de la carpeta de forma recursiva; todos los favoritos de un usuario se pueden encontrar enviando la solicitud a remote.php/dav/files/user.
Cabeceras especiales¶
Cabeceras de solicitud¶
Se pueden establecer algunas cabeceras especiales que APS Conecta Gestión interpretará.
Cabecera |
Descripción |
Ejemplo |
|---|---|---|
X-OC-MTime |
Permite especificar una hora de modificación. La respuesta contendrá la cabecera |
|
X-OC-CTime |
Permite especificar una hora de creación. La respuesta contendrá la cabecera |
|
OC-Checksum |
Una suma de comprobación que se almacenará en la BD. En las subidas |
|
X-Hash |
En las solicitudes |
|
OC-Total-Length |
Contiene el tamaño total del archivo durante una subida por fragmentos. Esto permite al servidor abortar antes si la cuota restante del usuario no es suficiente. |
|
X-NC-WebDAV-AutoMkcol |
Si se establece en |
|
OC-Chunked (obsoleta) |
Se usaba en la subida por fragmentos heredada para diferenciar una subida normal de una subida por fragmentos. Permitía comprobar la cuota y otras cosas. Hoy en día, en su lugar hay que proporcionar la cabecera |
Obsoleta Ya no es necesario proporcionarla |
Cabeceras de respuesta¶
Cabecera |
Descripción |
Ejemplo |
|---|---|---|
OC-Etag |
En la creación, el movimiento y la copia, la respuesta contiene el etag del archivo. |
|
OC-FileId |
En la creación, el movimiento y la copia, la respuesta contiene el fileid del archivo. |
Formato: Ejemplo: |
X-NC-OwnerId |
En la creación, la respuesta contiene el ID del propietario. |
Ejemplo: |
X-NC-Permissions |
En la creación, la respuesta contiene la cadena de permisos. |
Ejemplo: |