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
id 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.