API de dossiers

Utilisez l'API Folder pour travailler avec des dossiers dans l'espace de travail Amazon Managed Grafana.

L'identifiant (id) d'un dossier est une valeur numérique à incrémentation automatique qui n'est unique que par espace de travail. L'identifiant unique (uid) d'un dossier peut être utilisé pour identifier de manière unique un dossier entre plusieurs espaces de travail. Il est généré automatiquement si vous ne le fournissez pas lors de la création d'un dossier. L'uid permet d'avoir des URL cohérentes pour accéder au dossier et lors de la synchronisation du dossier entre plusieurs espaces de travail Amazon Managed Grafana. L'utilisation de l'UID signifie que la modification du titre d'un dossier ne rompt aucun lien enregistré vers ce dossier.

L'UID peut avoir une longueur maximale de 40 caractères.

Les dossiers ne peuvent pas être imbriqués.

Note

Pour utiliser une API Grafana avec votre espace de travail Amazon Managed Grafana, vous devez disposer d'un jeton d'API Grafana valide. Vous l'incluez dans le Authorization champ de la demande d'API. Pour plus d'informations sur la création d'un jeton pour authentifier vos appels d'API, consultezAuthentifiez-vous avec des jetons.

Le dossier General, avec un id 0, ne fait pas partie de l'API Folder. Vous ne pouvez pas utiliser l'API Folder pour récupérer des informations sur le dossier général.

Créer un dossier

POST /api/folders

Crée un nouveau dossier.

Exemple de demande

POST /api/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "uid": "nErXDvCkzz",
  "title": "Department ABC"
}

Schéma de corps JSON :

• uid — Identifiant unique facultatif. Si la valeur est nulle, un nouvel UID est généré.

• title — Titre du dossier.

Exemple de réponse

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
}

Codes de statut :

• 200 — Créé

• 400 — Erreur telle qu'un JSON non valide, des champs non valides ou manquants

• 401 — Non autorisé

• 403 — Accès refusé

Mettre à jour le dossier

PUT /api/folders/:uid

Met à jour le dossier existant correspondant à l'UID.

Exemple de demande

PUT /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "title":"Department DEF",
  "version": 1
}

Schéma de corps JSON :

• uid — Modifie l'identifiant unique, s'il est fourni.

• title — Titre du dossier.

• version — Indiquez la version actuelle pour pouvoir remplacer le dossier. Pas nécessaire sioverwrite=true.

• overwrite : défini sur true pour remplacer le dossier existant par une version plus récente.

Exemple de réponse

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
}

Codes de statut :

• 200 — Créé

• 400 — Erreur telle qu'un JSON non valide, des champs non valides ou manquants

• 401 — Non autorisé

• 403 — Accès refusé

• 404 — Dossier introuvable

• 412 — Échec de la précondition

Le code d'état 412 est utilisé pour expliquer pourquoi le dossier ne peut pas être mis à jour.

• Le dossier a été modifié par quelqu'un d'autre status=version-mismatch

Le corps de la réponse possède les propriétés suivantes :

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"
}

Obtenir tous les dossiers

GET /api/folders

Renvoie tous les dossiers que vous êtes autorisé à consulter. Vous pouvez contrôler le nombre maximum de dossiers renvoyés à l'aide du paramètre de limit requête. La valeur par défaut est 1000.

Exemple de demande

GET /api/folders?limit=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Exemple de réponse

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "uid": "nErXDvCkzz",
    "title": "Department ABC"
  },
  {
    "id":2,
    "uid": "k3S1cklGk",
    "title": "Department RND"
  }
]

Obtenir un dossier par UID

GET /api/folders/:uid

Renvoie tous les dossiers qui correspondent à l'UID donné.

Exemple de demande

GET /api/folders/nErXDvCkzzh HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Exemple de réponse

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
}

Codes de statut :

• 200 — Trouvé

• 401 — Non autorisé

• 403 — Accès refusé

• 404 — Non trouvé

Obtenir un dossier par identifiant

GET /api/folders/id/:id

Renvoie le dossier qui correspond à l'identifiant donné.

Exemple de demande

GET /api/folders/id/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Exemple de réponse

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
}

Codes de statut :

• 200 — Trouvé

• 401 — Non autorisé

• 403 — Accès refusé

• 404 — Non trouvé

Supprimer le dossier par UID

DELETE /api/folders/:uid

Supprime le dossier correspondant à l'UID, ainsi que tous les tableaux de bord stockés dans le dossier. Cette opération ne peut pas être annulée.

Exemple de demande

DELETE /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Exemple de réponse

HTTP/1.1 200
Content-Type: application/json

{
  "message":"Folder deleted",
  "id": 2
}

Codes de statut :

• 200 — Supprimé

• 401 — Non autorisé

• 403 — Accès refusé

• 404 — Non trouvé