Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # API de carpetas Use la API de carpetas para trabajar con las carpetas en el espacio de trabajo de Amazon Managed Grafana. El identificador (id) de una carpeta es un valor numérico que se incrementa automáticamente y solo es único por espacio de trabajo. El identificador único (uid) de una carpeta se puede utilizar para identificar de forma única una carpeta entre varios espacios de trabajo. Se genera automáticamente si no lo proporciona al crear una carpeta. El uid permite disponer de URL coherentes para acceder a las carpetas y al sincronizarlas entre varios espacios de trabajo de Amazon Managed Grafana. El uso del uid significa que al cambiar el título de una carpeta no se interrumpe ningún enlace marcado a esa carpeta. El uid puede tener una longitud máxima de 40 caracteres. Las carpetas no se pueden anidar. **nota** Para usar una API de Grafana con tu espacio de trabajo de Grafana gestionado por Amazon, debes tener un token de cuenta de servicio válido. Lo incluye en el campo `Authorization` de la solicitud de API. La carpeta **General**, cuyo `id` es 0, no forma parte de la API de carpetas. No puede usar la API de carpetas para recuperar información sobre la carpeta general. ## Creación de una carpeta ``` POST /api/folders ``` Crea una carpeta nueva. **Ejemplo de solicitud** ``` POST /api/folders HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "uid": "nErXDvCkzz", "title": "Department ABC" } ``` Esquema de cuerpo JSON: + **uid**: identificador único opcional. Si su valor es “null”, se genera un nuevo uid. + **title**: título de la carpeta. **Ejemplo de respuesta** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC", "url": "/dashboards/f/nErXDvCkzz/department-abc", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Códigos de estado: + **200**: creado. + **400**: error (como JSON no válido, campos no válidos o campos faltantes). + **401**: no autorizado. + **403**: acceso denegado. ## Actualización de una carpeta ``` PUT /api/folders/:uid ``` Actualiza la carpeta existente que coincide con el uid. **Ejemplo de solicitud** ``` PUT /api/folders/nErXDvCkzz HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "title":"Department DEF", "version": 1 } ``` Esquema de cuerpo JSON: + **uid**: cambia el identificador único, si se proporciona. + **title**: título de la carpeta. + **version**: proporcione la versión actual para poder sobrescribir la carpeta. No es necesario si `overwrite=true`. + **overwrite**: se establece en `true` para sobrescribir la carpeta existente con una versión más reciente. **Ejemplo de respuesta** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department DEF", "url": "/dashboards/f/nErXDvCkzz/department-def", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Códigos de estado: + **200**: creado. + **400**: error (como JSON no válido, campos no válidos o campos faltantes). + **401**: no autorizado. + **403**: acceso denegado. + **404**: no se encontró la carpeta. + **412**: error en la condición previa. El código de estado **412** se usa para explicar por qué no se puede actualizar la carpeta. + Otra persona ha cambiado la carpeta `status=version-mismatch` El cuerpo de la respuesta tiene las siguientes propiedades: ``` HTTP/1.1 412 Precondition Failed Content-Type: application/json; charset=UTF-8 Content-Length: 97 { "message": "The folder has been changed by someone else", "status": "version-mismatch" } ``` ## Obtención de todas las carpetas ``` GET /api/folders ``` Devuelve todas las carpetas para las que tiene permiso de visualización. Puede controlar el número máximo de carpetas devueltas mediante el parámetro de consulta `limit`. El valor predeterminado es 1000. **Ejemplo de solicitud** ``` GET /api/folders?limit=10 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Ejemplo de respuesta** ``` HTTP/1.1 200 Content-Type: application/json [ { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC" }, { "id":2, "uid": "k3S1cklGk", "title": "Department RND" } ] ``` ## Obtención de una carpeta por uid ``` GET /api/folders/:uid ``` Devuelve todas las carpetas que coinciden con el uid dado. **Ejemplo de solicitud** ``` GET /api/folders/nErXDvCkzzh HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Ejemplo de respuesta** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC", "url": "/dashboards/f/nErXDvCkzz/department-abc", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Códigos de estado: + **200**: encontrado. + **401**: no autorizado. + **403**: acceso denegado. + **404**: no encontrado. ## Obtención de una carpeta por id ``` GET /api/folders/id/:id ``` Devuelve la carpeta que coincide con el id dado. **Ejemplo de solicitud** ``` GET /api/folders/id/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Ejemplo de respuesta** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC", "url": "/dashboards/f/nErXDvCkzz/department-abc", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Códigos de estado: + **200**: encontrado. + **401**: no autorizado. + **403**: acceso denegado. + **404**: no encontrado. ## Eliminación de una carpeta por uid ``` DELETE /api/folders/:uid ``` Elimina la carpeta que coincide con el uid y también elimina todos los paneles almacenados en la carpeta. Esta operación no se puede revertir. **Ejemplo de solicitud** ``` DELETE /api/folders/nErXDvCkzz HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Ejemplo de respuesta** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Folder deleted", "id": 2 } ``` Códigos de estado: + **200**: eliminado. + **401**: no autorizado. + **403**: acceso denegado. + **404**: no encontrado.