6.1.2. Fichiers joints

L’API Bugzilla pour créer, modifier et obtenir des détails sur les fichiers joints.

6.1.2.1. Obtention d’un fichier joint

Ceci permet d’obtenir des données sur les fichiers joints, une liste de bogues et/ou des numéros de fichiers joints. Les fichiers joints confidentiels ne seront renvoyés que si vous êtes dans le groupe approprié ou si vous êtes la personne ayant soumis le fichier.

Requête

Pour obtenir tous les fichiers joints d’un bogue :

GET /rest/bug/(bug_id)/attachment

Pour obtenir un fichier joint spécifique en fonction de son numéro :

GET /rest/bug/attachment/(attachment_id)

Un des deux éléments ci-dessous doivent être spécifiés.

nom	type	description
bug_id	int	Numéro de bogue (entier).
attachment_id	int	Numéro de fichier joint (entier).

Réponse

{
   "bugs" : {
      "1345" : [
         { (attachment) },
         { (attachment) }
      ],
      "9874" : [
         { (attachment) },
         { (attachment) }
      ],
   },
   "attachments" : {
      "234" : { (attachment) },
      "123" : { (attachment) },
   }
}

Un objet contenant deux éléments : bugs et attachments.

Les fichiers joints pour le bogue que vous avez spécifiés dans l’argument bug_id dans la saisie sont renvoyés en bugs sur la sortie. bugs est un objet qui a un numéro de bogue entier pour clés et les valeurs sont des tableaux d’objets de fichiers joints. (Les champs pour les fichiers joints sont décrits ci-dessous).

Pour les fichiers que vous spécifiez directement dans attachment_id, ils sont renvoyés dans attachments sur la sortie. C’est un objet où le numéro de fichier joint pointe directement sur les objets décrivant le fichier joint individuel.

Les champs pour chaque fichier joint (ou il est indiqué (attachment) dans l’exemple ci-dessus) sont :

nom	type	description
data	base64	Les données brutes du fichier joint, encodé en Base64.
size	int	La longueur (en octets) du fichier joint.
creation_time	datetime	La date de création du fichier joint.
last_change_time	datetime	La date de dernière modification du fichier joint.
id	int	Le numéro du fichier joint.
bug_id	int	Le numéro du bogue auquel est joint le fichier.
file_name	string	Le nom du fichier joint.
summary	string	Une courte description du fichier joint.
content_type	string	Le type MIME du fichier joint.
is_private	boolean	`true` si le fichier joint est confidentiel (seulement visible d’un groupe appelé `insidergroup`, `false` dans le cas contraire).
is_obsolete	boolean	`true` si le fichier joint est obsolète, `false` dans le cas contraire.
is_patch	boolean	`true` si le fichier joint est un correctif, `false` dans le cas contraire.
creator	string	L’identifiant de connexion de l’utilisateur qui a joint le fichier.
flags	array	Un tableau d’objets, chacun contenant les informations sur l’étiquette actuellement définie pour chaque fichier joint. Chaque étiquette contient des éléments décrits dans l’objet Étiquette ci-dessous.

Objet Étiquette :

nom	type	description
id	int	Le numéro de l’étiquette.
name	string	Le nom de l’étiquette.
type_id	int	Le numéro de type de l’étiquette.
creation_date	datetime	L’horodatage de création de l’étiquette.
modification_date	datetime	L’horodatage de dernière modification de l’étiquette.
status	string	L’état actuel de l’étiquette : ?, + ou -.
setter	string	L’identifiant de connexion de l’utilisateur qui a créé ou modifié en dernier l’étiquette.
requestee	string	L’identifiant de connexion de l’utilisateur à qui a été demandée la revue. Note : ce champ est renvoyé seulement si ce champ a été défini par le demandeur.

6.1.2.2. Création d’un fichier joint

Ceci permet de joindre un fichier à un bogue dans Bugzilla.

Requête

Pour créer un fichier joint su un bogue existant :

POST /rest/bug/(bug_id)/attachment

{
  "ids" : [ 35 ],
  "is_patch" : true,
  "comment" : "Ceci est un nouveau commentaire de fichier joint",
  "summary" : "Courte description du fichier joint",
  "content_type" : "text/plain",
  "data" : "(contenu encodé en base64)",
  "file_name" : "test_attachment.patch",
  "obsoletes" : [],
  "is_private" : false,
  "flags" : [
    {
      "name" : "review",
      "status" : "?",
      "requestee" : "user@bugzilla.org",
      "new" : true
    }
  ]
}

Les paramètres à inclure dans le corps de la requête POST, ainsi que le format des données renvoyées, sont les mêmes que ci-dessous. Le paramètre bug_id sera écrasé car il est extrait du chemin de l’URL.

nom	type	description
ids	array	Les numéros ou alias de bogues auxquels vous voulez joindre ce fichier. Les mêmes fichier et commentaire seront ajoutés à tous ces bogues.
data	string	Le contenu du fichier joint. Vous devez encoder celui-ci en base64 en utilisant une bibliothèque cliente appropriée telle que `MIME::Base64` pour Perl.
file_name	string	Le nom de fichier qui sera affiché dans l’interface utilisateur pour ce fichier joint ainsi que le nombre de copies téléchargées.
summary	string	Une courte description du fichier joint.
content_type	string	Le type MIME du fichier joint, comme `text/plain` ou `image/png`.
comment	string	Un commentaire à ajouter relatif à ce fichier joint.
is_patch	boolean	`true` si Bugzilla doit traiter ce fichier joint comme un correctif. Si vous indiquez ceci, vous n’avez pas besoin de spécifier un `content_type`. Le `content_type` du fichier joint sera forcé en `text/plain`. Par défaut à `false` si rien n’est indiqué.
is_private	boolean	`true` si ce fichier doit être considéré comme confidentiel (restreint au groupe `insidergroup`), `false` si le fichier est public. Par défaut à `false` si rien n’est indiqué.
flags	array	Objets Étiquettes à ajouter au fichier. Le format de l’objet est décrit ci-dessous.

Objet Étiquette :

Pour créer une étiquette, doit être au moins indiqué le status et le type_id ou le name. Optionnellement, le nom du développeur à qui est demandée l’étiquette peut être indiqué si le type de l’étiquette le permet.

nom	type	description
name	string	Le nom du type de l’étiquette.
type_id	int	Le numéro interne du type de l’étiquette.
status	string	Le nouvel état de l’étiquette (c’est-à-dire `?`, `+`, `-` ou `X` pour aucun état).
requestee	string	L’identifiant de connexion de l’utilisateur à qui a été demandée l’étiquette, si le type de l’étiquette permet de demander la revue à un utilisateur spécifique.

Réponse

{
  "ids" : [
    "2797"
  ]
}

nom	type	description
ids	array	Numéro du fichier joint créé.

6.1.2.3. Mise à jour de fichier joint

Ceci permet de mettre à jour les méta-données d’un fichier joint dans Bugzilla.

Requête

Pour mettre à jour les méta-données d’un fichier joint existant :

PUT /rest/bug/attachment/(attachment_id)

{
  "ids" : [ 2796 ],
  "summary" : "Fichier de test XML",
  "comment" : "Modification du correctif en fichier XML",
  "content_type" : "text/xml",
  "is_patch" : 0
}

nom	type	description
attachment_id	int	Numéro du fichier joint (entier).
ids	array	Les numéros des fichiers joints que vous voulez mettre à jour.

nom	type	description
file_name	string	Le nom de fichier qui sera affiché dans l’interface utilisateur pour ce fichier joint.
summary	string	Une courte description du fichier.
comment	string	Un commentaire optionnel à ajouter pour le fichier joint.
content_type	string	Le type MIME du fichier, comme `text/plain` ou `image/png`.
is_patch	boolean	`true` si Bugzilla doit traiter ce fichier comme un correctif. Si vous indiquez ceci, vous n’avez pas besoin de spécifier un `content_type`. Le `content_type` du fichier sera forcé à `text/plain`.
is_private	boolean	`true` si le fichier doit être considéré comme confidentiel (restreint au groupe `insidergroup`), `false` si le fichier joint est public.
is_obsolete	boolean	`true` si le fichier est obsolète, `false` dans le cas contraire.
flags	array	Un tableau d’objets Étiquette contenant les modifications des étiquettes. Le format des objets est décrit ci-dessous.

Objet Étiquette :

Les valeurs suivantes peuvent être spécifiées. Il doit être au moins indiqué le status et le type_id ou le name. Si un type_id ou un name correspond à une seule étiquette actuellement définie, l’étiquette sera mise à jour à moins que new soit spécifié.

nom	type	description
name	string	Le nom de l’étiquette qui sera créée ou mise à jour.
type_id	int	Le numéro interne du type d’étiquette qui sera créé ou mis à jour. Vous devez indiquer le `type_id` si plus d’un type d’étiquette de même nom existe.
status	string	Le nouvel état de l’étiquette (c’est-à-dire `?`, `+`, `-` ou `X` pour aucun état).
requestee	string	L’identifiant de connexion de l’utilisateur à qui est demandée l’étiquette si le type de l’étiquette permet de demander à un utilisateur spécifique.
id	int	Numéro de l’étiquette à mettre à jour. Vous devez spécifier l”`id` si plus d’une étiquette est définie avec le même nom.
new	boolean	Définir à true si vous voulez spécifiquement qu’une nouvelle étiquette soit crée.

Réponse

{
  "attachments" : [
    {
      "changes" : {
        "content_type" : {
          "added" : "text/xml",
          "removed" : "text/plain"
        },
        "is_patch" : {
          "added" : "0",
          "removed" : "1"
        },
        "summary" : {
          "added" : "Fichier de test XML",
          "removed" : "test de correctif"
        }
      },
      "id" : 2796,
      "last_change_time" : "2014-09-29T14:41:53Z"
    }
  ]
}

attachments (tableau) Change les objets avec les éléments suivants :

nom

type

description

int

Le numéro du fichier joint qui a été mis à jour.

last_change_time

datetime

L’heure exacte à laquelle la mise à jour a été faite, pour ce fichier joint. Si aucune mise à jour n’a été faite (c’est-à-dire, si aucune valeur de champ n’a été modifiée et si aucun commentaire n’a été ajouté) ce sera alors l’heure de la dernière mise à jour du du fichier joint.

changes

object

Les modifications qui ont été effectivement faites sur le fichier joint. Les clés sont les noms des champs qui ont été modifiés et les valeurs sont des objets contenant deux éléments:

added : (chaîne) Les valeurs qui ont été ajoutées à ce champ. Cela peut-être une liste séparée par des virgules ou des espaces si plusieurs valeurs ont été ajoutées.
removed : (chaîne) Les valeurs qui ont été supprimées de ce champ.

Cette documentation contient très probablement des bogues ; si vous en découvrez, veuillez les signaler ici.