REST API - Options pour les champs


Recherche et filtre dans la base de données

Par champ

Dans les requêtes HTTP, vous pouvez effectuer une recherche/filtre sur un ou plusieurs champs de la base Service Manager en utilisant les noms d’objets correspondants. Toutefois, vous ne pouvez utiliser qu’une seule fois le même objet dans la même requête (l’union n’est pas possible).

La syntaxe à utiliser est la suivante :

search={(prefix_object_name_1.)object_name_1}:{object_name_value_1}(,{(prefix_object_name_2.)object_name_2}:{object_name_value_2})
  • (prefix_object_name_x.) : Préfixe à indiquer uniquement lorsque l’objet souhaité est contenu dans un autre objet.
  • object_name_x : Nom de l’objet utilisé. Paramètre obligatoire.
  • object_name_value_x : Valeur de l’objet utilisé. Paramètre obligatoire.

 

exemple 

Check icon.png   Requêtes correctes
/employees?search=last_name:"Morley, Gaby"

/assets?search=asset_tag:"1012D"
/assets?search=employee.last_name:"Taverner, David"
/assets?search=department.department_en:"Finance"

/requests?search=department.department_en:"Industry"
/requests?search=status.status_en:"Closed"
/requests?search=status.status_en:"In Progress",submit_date_ut:this_week&sort=recipient.last_name+asc
/requests?search=recipient.last_name:"Morley, Gaby"
/requests?search=requestor.last_name:"Morley, Gaby"
/requests?search=recipient.last_name:"Morley, frédérique",status.status_en:"In Progress"
/requests?search=recipient.e_mail:fpachelbel@evtry.com,status.status_en:"Escalated"
/requests?search=recipient.e_mail:adam@evtry.com,status.status_en:"In Progress",submit_date_ut:today
/requests?search=recipient.last_name:"Adam, George",status.status_en:"Closed",submit_date_ut:this_year
/requests?search=recipient.last_name:"Adam, George",status.status_en:"In Progress",submit_date_ut:this_week&sort=submit_date_ut+asc
Not check icon.png   Requêtes incorrectes
/requests?search=recipient.e_mail:adam@evtry.com,morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com,recipient.e_mail:morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&recipient.e_mail:morley@evtry.com

Par date

Note : Le format de date attendu est celui employé par l’utilisateur de l’API REST Service Manager connecté.

  • Le filtrage par date peut être effectué sur tous les champs de type Date.
  • Les intervalles de dates sont interprétés comme inclusifs.
  • Vous pouvez utiliser des intervalles prédéfinis.

exemple 

search=SUBMIT_DATE_UT:last_week
search=SUBMIT_DATE_UT:3daysbefore

Liste des intervalles prédéfinis

    Note : Les valeurs sont non sensibles à la casse.

  • this_year
  • this_month   
  • this_week
  • this_day / today
  • last_year
  • last_month
  • last_week
  • first_quarter / Q1
  • second_quarter / Q2
  • third_quarter / Q3
  • fourth_quarter / last_quarter/ Q4
  • next_day / tomorrow
  • next_week
  • next_month
  • next_year
  • daysbefore
  • daysafter
  • Vous pouvez utiliser des intervalles explicites.
    Note : Tous les exemples correspondent à un utilisateur connecté aux USA (format de date AAAA-MM-JJ).

Par date

exemple   Demandes créées du 09/07/2020 au 10/07/2020

Search=SUBMIT_DATE_UT:(2020-07-09;2020-07-10)

     Résultat :

{
"RFC_NUMBER": "I200709_000001",
"SUBMIT_DATE_UT": "2020-07-09T04:34:59.593-04:00"
}

Par date et heure

Note : L'utilisation de cette option est possible depuis la version Autumn 2020 de Service Manager.

exemple   Demandes créées du 09/07/2020 à 00h00 au 09/07/2020 à 23h59

search=SUBMIT_DATE_UT:(2020-07-09T00:00:00;2020-07-09T23:59:00)

    Résultat : 04:34:59.593 correspond à 08:34 en heure UT

{
"RFC_NUMBER": "I200709_000001",
"SUBMIT_DATE_UT": "2020-07-09T04:34:59.593-04:00"
}

exemple   Demandes créées du 09/07/2020 à 12h30 au 09/07/2020 à 12h35 dans le fuseau horaire -4 heures

search=SUBMIT_DATE_UT:(2020-07-09T12:00:00.000-04:00;2020-07-09T12:35:00.000-04:00)&fields=SUBMIT_DATE_UT 

    Résultat : 04:34:59.593 correspond à 08:34 en heure UT avec le fuseau horaire -4 heures

{
"RFC_NUMBER": "I200709_000001",
"SUBMIT_DATE_UT": "2020-07-09T04:34:59.593-04:00"
}

Formats de date

Note : L'utilisation du paramètre formatDate dans la chaîne de requête HTTP est possible depuis la version Oxygène 1.7 - Build 2018.1.131.0 de Service Manager.

De nombreuses options sont disponibles pour formater les dates / heures et les informations relatives au fuseau horaire en utilisant le paramètre formatDate dans la chaîne de requête HTTP.

Lorsque vous utilisez ce paramètre, de nouveaux champs suffixés par _FORMAT sont ajoutés dans le résultat de la requête HTTP, affichant la date dans le format souhaité.

Remarques

  • Tous les champs de type Date peuvent être formatés.

    exemple  LAST_UPDATE, MAX_RESOLUTION_DATE_UT

  • Le même formatage de date s'applique à tous les champs spécifiés dans la chaîne de requête HTTP.

Attention

  • Ce paramètre sert uniquement pour afficher la date dans le format souhaité. Il ne permet pas de filtrer les informations sur une date. Pour cela, utilisez le paramètre search lorsque la méthode le permet.

Exemples

Formats de date

Format Résultat

formatDate = l/M/Y

Friday/Nov/2018

formatDate = l jS \of F Y h:i:s A

Friday 16th of November 2018 12:00:00 AM

formatDate=Y-m-d H:i:s

2018-03-10 17:16:18

Utilisation du paramètre formatDate

Sans formatage des champs de type Date

https://{your_server}/api/v1/{your_account}/requests?max_rows=1&fields=LAST_UPDATE,MAX_RESOLUTION_DATE_UT

         Résultat :

{
   "HREF": "https://{your_server}/api/v1/{your_account}/requests?max_rows=1&fields=LAST_UPDATE,MAX_RESOLUTION_DATE_UT"
   "record_count": "1",
   "total_record_count": "13818",
   "records": [
        {
           "HREF": "https://{your_server}/api/v1/{your_account}/requests/000002",
           "RFC_NUMBER": "000002",
           "LAST_UPDATE": "2018-11-01T06:17:46.297-05:00",
           "MAX_RESOLUTION_DATE_UT": "2018-11-04T20:00:00.000-04:00"
        }
    ]
}

Avec formatage des champs de type Date

https://{your_server}/api/v1/{your_account}/requests?max_rows=1&fields=LAST_UPDATE,MAX_RESOLUTION_DATE_UT&formatDate=l/M/Y

         Résultat : Les champs LAST_UPDATE_FORMAT et MAX_RESOLUTION_DATE_UT_FORMAT sont ajoutés, avec le format de date souhaité.

{
   "HREF": "https:// {your_server}/api/v1/{your_account}/requests?max_rows=1&fields=LAST_UPDATE,MAX_RESOLUTION_DATE_UT&formatDate=l/M/Y"
   "record_count": "1",
   "total_record_count": "13818",
   "records": [
        {
           "HREF": "https:// {your_server}/api/v1/{your_account}/requests/000002",
           "RFC_NUMBER": "000002",
           "LAST_UPDATE": "2018-11-01T06:17:46.297-05:00",
           "MAX_RESOLUTION_DATE_UT": "2018-11-04T20:00:00.000-04:00",
           "LAST_UPDATE_FORMAT": "Thursday/Nov/2018",
           "MAX_RESOLUTION_DATE_UT_FORMAT": "Sunday/Nov/2018"
        }
    ]
}

Options de formatage

Jour

Format Description Exemple
d Numéro du jour dans le mois
  • sur 2 chiffres (avec un zéro devant)
01 à 31
D Nom abrégé du jour
  • sur 3 lettres
  • dans la langue locale du serveur - à défaut, en anglais
Sun (dimanche) à Sat (samedi)
j Numéro du jour dans le mois
  • sans zéro devant
1 à 31
l

(L minuscule)

Nom complet du jour
  • en anglais
Sunday (dimanche) à Saturday (samedi)
N Numéro du jour dans la semaine suivant la norme ISO-8601
  • la semaine commence le lundi
1 (lundi) à 7 (dimanche)
S Suffixe ordinal du numéro du jour : st, nd, rd ou th
  • sur 2 lettres
  • en anglais
  • Note : Peut être utilisé avec j
1st, 2nd, 3rd, 4th
w Numéro du jour dans la semaine
  • la semaine commence le dimanche
0 (dimanche) à 6 (samedi)
z Numéro du jour dans l'année
  • sans zéro devant
0 à 365

Semaine

Format Description Exemple
W Numéro de la semaine dans l'année suivant la norme ISO-8601
  • la semaine commence le lundi
42 = 42ème semaine de l'année

Mois

Format Description Exemple
F Nom complet du mois
  • en anglais
January (janvier) à December (décembre)
m Numéro du mois dans l'année
  • sur 2 chiffres (avec un zéro devant)
01 (janvier) à 12 (décembre)
M Nom abrégé du mois
  • sur 3 lettres
  • dans la langue locale du serveur - à défaut, en anglais
Jan (janvier) à Dec (décembre)
n Numéro du mois dans l'année
  • sans zéro devant
1 (janvier) à 12 (décembre)
t Nombre de jours dans le mois 28 à 31

Année

Format Description Exemple
L Année bissextile 0 = non bissextile ; 1 = bissextile
o Année suivant la norme ISO-8601 1999 ; 2003
Y Année sur 4 chiffres 1999 ; 2003
y Année sur 2 chiffres 99 ; 03

Heure

Format Description Exemple
a Indication de ante meridiem (matin) / post meridiem (après-midi) après les heures
  • en minuscules
15am ; 15pm
A Indication de ante meridiem (matin) / post meridiem (après-midi) après les heures
  • en majuscules
15AM ; 15PM
B Heure Internet
000 à 999
g Heure sur 12 heures
  • sans zéro devant
1 à 12
G Heure sur 24 heures
  • sans zéro devant
0 à 23
h Heure sur 12 heures
  • sur 2 chiffres (avec un zéro devant)
01 à 12
H Heure sur 24 heures
  • sur 2 chiffres (avec un zéro devant)
01 à 23
i Minute
  • sur 2 chiffres (avec un zéro devant)
00 à 59
s Seconde
  • sur 2 chiffres (avec un zéro devant)
00 à 59
u Microseconde 654321
v Milliseconde 654

Date / Heure complètes

Format Description Exemple
c Date suivant la norme ISO-8601 2004-02-12T15 :19 :21+00 :00
r Date suivant la référence RFC 2822 Thu, 21 Dec 2000 16 :01 :07+0200
U Nombre de secondes écoulées depuis le début de l'ère Unix
  • date de référence : 1er janvier 1970 à minuit UTC précise
5/3/2019 à 15:44:18 = 1551800658 secondes

Fuseau horaire

Format Description Exemple
e Identifiant du fuseau horaire UTC ; GMT ; Atlantic/Azores
I

(i majuscule)

Heure d'hiver ou heure d'été 0 = Heure d'hiver ; 1 = Heure d'été
O Décalage horaire avec le méridien de Greenwich (GMT), en heures +0200
P Décalage horaire avec le méridien de Greenwich (GMT), en heures:minutes +02:00
T Abréviation du fuseau horaire EST ; MDT
Z Décalage horaire avec le temps universel coordonné (UTC), en secondes
  • décalage des zones à l'ouest de la zone UTC : négatif
  • décalage des zones à l'est de la zone UTC : positif
-43200 à 50400
Tags:
Modifié par Christine Daussac le 2021/04/20 15:32
Créé par Administrator XWiki le 2019/03/19 15:32

Raccourcis

L'actualité mensuelle
•  Newsletter

Tous les changements
•  Service Manager
•  Service Apps
•  Self Help
•  Service Bots

Powered by XWiki ©, EasyVista 2021