Das REST API bietet ausschließlich eine generelle Authentisierung ohne Zugriffssteuerung für einzelne Benutzer. Auf das API kann über das Rest Interface zugegriffen werden. Es dient ausschließlich dazu, Requests der REST Frontends zu verarbeiten.

Les requêtes de recherche permettent de retrouver les courriels archivés. Comme tous les courriels, y compris leurs pièces jointes, sont indexés en texte intégral, il est possible de les retrouver en fonction de leur contenu ou de leurs attributs (et bien sûr de toute combinaison d'attributs).

Suchanfragen werden mittels eines HTTP bzw. HTTPS URL aufgerufen. Die Syntax ist dabei grundsätzlich:

http://bennohost:21080/search/{requête de recherche} 

Der dem Keyword „search“ folgende Slash (/) ist dabei obligatorisch. Die Suchanfrage selbst setzt sich aus mehreren Parametern zusammen. Diese werden in der üblichen Form in dem URL codiert:

?option1=valeur1&option2=valeur2&option3=valeur3 

La requête de recherche complète se présente donc sous le format suivant :

http://bennohost:21080/search/?option1=wert1&option2=wert2... 

Remarque : Pour des raisons d’impression, certaines URL s’affichent sur plusieurs lignes. Elles doivent cependant être saisies sur une seule ligne, sans espaces, etc

Voici la représentation syntaxique des requêtes de recherche. Vous trouverez plus bas des exemples concrets de requêtes de recherche.

Les requêtes de recherche dans Benno MailArchiv sont toujours rédigées en utilisant la syntaxe de requête Apache Lucene. La syntaxe Lucene complète est disponible, par exemple, dans les sources suivantes :

• http://lucene.apache.org/core/3_6_2/queryparsersyntax.html
• http://www.lucenetutorial.com/lucene-query-syntax.html

http://bennohost:21080/search/?archive=container-identifier&query=suchanfrage

Exemple utilisant cURL :

curl -u benno2:<shared secret> \
  --data archive=BennoContainer \
  --data 'query=Text:hallo' \
  --data 'filterQuery=(*)' \
  --data start=0 \
  --data limit=20 \
  -D - -k http://localhost:21080/search/

http://bennohost:21080/search/?archive=container-identifier&filterQuery=filter&query=suchanfrage

L'utilisation de filtres dans les requêtes de recherche permet un traitement plus efficace de ces dernières. L'ordre de traitement dans Lucene est le suivant :

Premièrement, la requête est exécutée, puis la liste des résultats est filtrée à l'aide de la requête de filtrage.

Hinweis: Alle (auch komplexe) Suchanfragen können als „query“ gestaltet werden. Die Filterung kann bspw. ergänzend verwendet werden, um die Menge der Suchergebnisse auf E-Mails mit bestimmten Merkmalen einzugrenzen. Bspw. werden alle Suchanfragen der Benno MailArchiv WebApp über „query“ abgebildet, während die Benutzerberechtigungen durch Filter („filterQuery“) abgebildet werden.

Une requête de recherche comprend au moins les paramètres suivants :

• archive : identifiant unique du conteneur dans lequel la recherche doit être effectuée
• requête : La requête de recherche proprement dite
• filterQuery : Critères de filtrage appliqués aux résultats de la recherche après la recherche

Outre les paramètres obligatoires mentionnés ci-dessus, les requêtes de recherche peuvent également contenir les paramètres optionnels suivants :

• début: Numéro du premier élément de résultat à afficher (par défaut : 1) (1..n)
• limit: Nombre d'éléments à afficher dans le résultat (par défaut : 20)
• sort: Attribut, nach dem die Trefferliste sortiert werden soll (Standard: „sent“ (Sendedatum))
• sortAsc: Trier par ordre croissant (par défaut : false)
• complet: Affichage de tous les attributs des documents de messagerie (par défaut : faux)

• Valeurs de résultat (codes d'erreur HTTP de l'opération de recherche) :
  • 1xx - Informations
  • 2xx - OK…
  • 3xx - Demandes
  • 4xx - Erreurs temporaires
  • 5xx - Erreurs persistantes

• Données de résultats (résultats de recherche ou listes de résultats) :
• limite : telle que déterminée par les paramètres ou les valeurs par défaut
• trouvé : Nombre d'e-mails trouvés
• premier : Position dans les résultats de recherche de la première ligne affichée (1..n, 0 si aucune ligne n'a été affichée)
• dernière : Position dans le résultat de recherche de la dernière ligne affichée (1..n, 0 si aucune ligne n'a été affichée)
• nombre : Nombre de lignes dans cette valeur de retour
• résultats : liste des résultats ; tableau d’objets JSON ayant la structure suivante :
• De : Adresse de l'expéditeur
• à : Adresses de destination
• multipart : 1 si multipart, 0 sinon
• Sujet : Sujet
• Résumé : Résumé
• envoyé : la date d'expédition
• id : identifiant unique du courriel archivé (nécessaire pour le récupérer dans les archives)

Die nachfolgenden Beispiele für Suchanfragen beginnen alle mit dem folgenden HTTP URL. Dieser URL wird in den Beispielen nicht weiter extra aufgeführt.

http://bennohost:21080/search/ 

Veuillez noter que les requêtes de recherche sont généralement sur une seule ligne, même si elles sont souvent affichées sur plusieurs lignes ci-dessous !

Wie bereits eingangs erwähnt, raten wir ausdrücklich dazu, diese Form der Autorisierung nicht in browser-basierten Web-Anwendungen einzusetzen, da das Shared Secret im Klartext in der URL enthalten ist bzw. im Browser nachgelesen werden kann!

http://benno2:shared-secret@localhost:21080/search/... 

?archive=BennoContainer&query=(Expéditeur :*hansen-und-meyer*) 

Cette requête de recherche recherche tous les courriels dans le conteneur standard2 qui proviennent d'adresses d'expéditeur contenant littéralement « hansen-und-meyer ».

?archive=BennoContainer&query=((Expéditeur :*hansen-und-meyer*)) ET (Destinataire :vertrieb@*))

Cette requête de recherche recherche tous les courriels dans le conteneur standard qui proviennent d'adresses d'expéditeur contenant littéralement « hansen-und-meyer » ET dont les adresses de destinataire contiennent littéralement « vertrieb@ ».

?archive=BennoContainer&query=((Sender:*hansen-und-meyer*) AND (Date:[201308231020 TO 201308271605]))

Cette recherche concerne les courriels datant de la période comprise entre le 23/08/2013 à 10h20 et le 27/08/2013 à 16h05.

?archive=BennoContainer&filterQuery=(Destinataire :vertrieb@*)&query=(Expéditeur :*hansen-und-meyer*)

Cette requête de recherche porte également sur tous les courriels dont l'adresse de l'expéditeur contient littéralement « hansen-und-meyer ». Les résultats sont ensuite filtrés. Tous les courriels dont l'adresse du destinataire ne contient pas « vertrieb@ » sont exclus.

Comme nous l'avons vu, les deux voies mènent au même résultat.

?archive=BennoContainer&query=((Expéditeur :*hansen-und-meyer*)) (Destinataire :vertrieb@*))

Cette requête de recherche recherche tous les courriels dans le conteneur standard qui proviennent d'adresses d'expéditeur contenant littéralement « hansen-und-meyer » OU dont les adresses de destinataire contiennent littéralement « vertrieb@ ».

?archive=BennoContainer&query=HEADER-MESSAGE-ID:4AC1F407.321@lw-systems.net

Cette requête de recherche recherche l'e-mail avec l'en-tête Message-ID : 4AC1F407.321@lw-systems.net .

Outre les critères de recherche relatifs à l'expéditeur et au destinataire, d'autres critères sont disponibles. La liste complète de ces critères figure en annexe de cette documentation (voir la section « Critères de recherche dans les requêtes »).

Hinweis: Alle Suchkriterien können in Suchanfragen in beliebiger Form (UND, ODER) und in beliebiger Reihenfolge miteinander kombiniert werden.

Der API-Call zum Zugriff auf eine archivierte E-Mail dient dazu, eine E-Mail (incl. etwaiger Attachements) aus dem Archiv zu holen. Da jede E-Mail im Archiv eindeutig identifiziert ist, erfolgt der Zugriff über diesen eindeutigen Identifyer.

Remarque : Pour des raisons d’impression, certaines URL s’affichent sur plusieurs lignes. Elles doivent cependant être saisies sur une seule ligne, sans espaces, etc

Voici la représentation syntaxique d'une requête de recherche. Vous trouverez plus bas des exemples concrets de récupération d'e-mails.

Der Aufruf erfolgt analog der zu Suchanfragen als HTTP URL. Die Syntax ist dabei grundsätzlich:

http://bennohost:21080/mail/?archive=identifiant-container&id=id 

La récupération d'un courriel se compose des deux paramètres suivants :

• archive : identifiant unique du conteneur à partir duquel le courriel doit être lu
• id : L’identifiant unique de l’e-mail (ID), y compris le nom de la boîte au format conteneur. <box»<mailid>

Die aus dem Archiv gelesene E-Mail wird standardmäßig als JSON Objekt an das aufrufende Programm zurückgegeben. Mittels der Option format kann die Rückgabe der E-Mail im „raw“ Format, also RFC 822 bzw. RFC 2822 (Plaintext) erzwungen werden.

• format=raw - Courriel de demande au RFC822
• skipUTF8Recode=true - Renvoyer l'e-mail dans son format d'origine
• header=true - Retourner l'en-tête secret

Attention ! Pour réindexer un courriel depuis le dépôt, il est nécessaire de le charger sans modifier l’encodage. Par conséquent, le paramètre ` skipUTF8Recode=true` obligatoire.

• 1xx - Informations
• 2xx - OK…
• 3xx - Demandes
• 4xx - Erreurs temporaires
• 5xx - Erreurs persistantes

Une pièce jointe peut être référencée par son nom de fichier ou par son identifiant.

http://bennohost:21080/attachment/?archive=identifiant-container&id=id&attachment=Nom_de_fichier

http://bennohost:21080/attachment/?archive=container-identifier&id=id&attachmentId=0

• archive : identifiant unique du conteneur à partir duquel le courriel doit être lu
• id : L’identifiant unique de l’e-mail (ID), y compris le nom de la boîte au format conteneur. <box»<mailid>
• Pièce jointe : Nom du fichier joint
• attachmentId : identifiant de la pièce jointe tel que spécifié dans la liste des pièces jointes.

http://localhost:21080/mail/?archive=BennoContainer&id=2012:1C6626F53B0B...67ADA0 FB4E

Dieser Abruf liest die E-Mail mit der eindeutigen ID „1C6626F53B0B...67ADA0 FB4E“ aus dem Archiv und gibt sie an das aufrufende Programm zurück. Die E-Mail wird dabei aus der Box „2012“ des Containers „BennoContainer“ gelesen.

Il est possible de rechercher des adresses électroniques en utilisant tout le contenu indexé. Les critères de recherche peuvent être saisis individuellement ou combinés à l'aide des opérateurs logiques « ET » et « OU ». Pour plus de détails sur la syntaxe, veuillez consulter les informations ci-dessus et la documentation Apache Lucene correspondante (URL ci-dessus).

Folgende Suchkriterien stehen über die API für Suchanfragen zur Verfügung:

• Date : Date de l'e-mail
• De : Adresse e-mail de l'expéditeur
• Destinataire : Adresses des destinataires (y compris À, Cc et Cci)
• Domaine du destinataire : Domaine du destinataire
• Expéditeur : Adresse e-mail de l'expéditeur
• SenderDomain : Domaine de l'expéditeur
• Taille : Taille du courriel
• Objet : Objet de l'e-mail
• À : Adresses des destinataires
• pièce jointe : Courriel avec pièce jointe
• id : Identifiant unique de l’e-mail dans l’archive
• Cc : Adresses des destinataires
• Texte : Rechercher des mots dans le texte du courriel (y compris le texte des pièces jointes)
• EN-TÊTE-XYZ : L’en-tête de courriel « XYZ » contient une valeur spécifique (le nom de l’en-tête doit être écrit en LETTRES MAJUSCULES)

La requête de recherche ci-dessous, par exemple, donne un ensemble de résultats de 2 adresses e-mail :

http://bennohost:21080/search/?archive=BennoContainer&query=(Sender:*hansen-und-meyer*)

Le résultat de la recherche (2 résultats) est renvoyé sous forme d'objets JSON et contient, par exemple, le contenu suivant :

{ "licenseValid":true, "limit":2, "results" { "id":"2012:748B034C4AF3004231D24B9DE2515822AB16485914AB3AE055C40DA336F4272F00", "SubjectRe: Demande de renseignements concernant un partenariat", "Date201206191122", "hasAttachment1", "To":["W. Robert"<w.robert@robert-druck.de> ], "Bcc":[], "Cc":[], "De":"info@hansen-und-meyer.de" }, { "id":"2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00", "Subject":"Re: Demande concernant un partenariat", "Date":"201206191122", "hasAttachment":"1", "To":["w.robert@robert-druck.de"], "Bcc":[], "Cc":[], "De":"info@hansen-und-meyer.de" } ], "last":1, "count":2, "overall":25, "first":0, "found":14 }

La recherche est effectuée exclusivement sur l'index Benno MailArchiv. Toutes les valeurs affichées ici correspondent directement au contenu de l'index, tandis que l'e-mail est lu depuis le dépôt et analysé séparément pour l'affichage.

Lors de l'indexation, l'horodatage de l'en-tête de date est converti au format UTC et enregistré dans le champ d'index correspondant. À l'affichage d'un courriel, cette valeur est convertie au format horaire local.

Beim direkten Zugriff auf das REST-API muss daher darauf geachtet werden, den Inhalt von „Date“ in die jeweils lokale Zeitzone zu konvertieren.

La représentation de ce résultat de recherche dans un langage de programmation tel que PHP ou Perl pourrait ressembler à ceci :

$VAR1 = { 'first' => 0, 'count' => 2, 'last' => 1, 'found' => 14, 'overall' => 25, 'licenseValid' => 1, 'limit' => 2, 'results' => [ { 'Cc' => [], 'Subject' => "Re: Request regarding\x{c3}\x{bc}partnership", 'Date' => '201206191122', 'Bcc' => [], 'hasAttachment' => '1', 'id' => '2012:748B034C4AF3004231D24B9DE2515822AB16485914AB3AE055C40DA336F4272F00', 'To' => ['"W. Robert"<w.robert@robert-druck.de> '], 'From' => 'info@hansen-und-meyer.de' }, { 'Cc' => [], 'Subject' => "Re: Demande concernant un partenariat", 'Date' => '201206191122', 'Bcc' => [], 'hasAttachment' => '1', 'id' => '2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00', 'To' => ['w.robert@robert-druck.de'], 'From' => 'info@hansen-und-meyer.de' } ] }

Voici un exemple de courriel extrait des archives :

http://bennohost:21080/mail/?archive=BennoContainer&id=2012:1C6626F5E02E1B3B0B74D...A83C130162B077AD6AB00

Le résultat (l'e-mail) est renvoyé par défaut sous forme d'objets JSON et contient, par exemple, les éléments suivants :

{ 'body' => [ { 'content-type' => 'text/plain', 'data' => "Cher Monsieur Robert, nous vous remercions de l'intérêt que vous portez à nos produits, comme en témoigne votre courriel. Vous trouverez ci-joint une offre et espérons avoir de vos nouvelles prochainement à ce sujet. Veuillez consulter le document PDF ci-joint pour prendre connaissance de nos conditions générales. Bien entendu, nous restons à votre disposition par téléphone pour toute question. Vous pouvez nous joindre au 0541/123456-1, du lundi au vendredi, de 9h00 à 17h00. Cordialement, Hansen & Meyer Paper Mill GmbH, au nom de Sabine Petersen, Hansen & Meyer Paper Mill GmbH | Seelenhof 5 | 49100 Schönlingen | Tél. : +49 541 123456-1 | info@hansen-und-meyer.de 63258 } ], 'header' => { 'Cc' => [], 'User-Agent' => 'Mozilla-Thunderbird 2.0.0.22 (X11/20090706)', 'Subject' => "Re: Request regarding\x{c3}\x{bc}partnership", 'MIME version' => '1.0', 'In-Reply-To' => '<4AC1E7D2.6070302@web.de>', 'Date' => 'Tue, 19 Jun 2012 13:22:38 +0200', 'Bcc' => [], 'Size' => 109490, 'References' => '<4AC1E7D2.6070302@web.de>', 'Message ID' => '<4AC1EDFE.8070406@web.de>', 'Content-Type' => 'multipart/mixed; boundary="------------070101070508030007040901"', 'To' => [ 'w.robert@robert-druck.de' ], 'From' => 'info@hansen-und-meyer.de' 'X-Benno-HashCheckPassed' => true, 'X-Benno-DateTS' => 1340104958 }, };

• 400 - Erreur de requête
• 404 - Conteneur introuvable
• 503 - Erreur interne
• 901 - Index non initialisé