Rubrique Gestion des événements API ouverte

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 4 minutes de lecture

    • L’API ouverte de rubrique Gestion des événements fournit un point de terminaison qui vous permet d’envoyer une rubrique via votre courtier de messages et de la stocker sur une ServiceNow instance.

    À l’aide de cette API, vous pouvez stocker les rubriques créées via votre courtier en messages dans la ServiceNow table Rubrique [rubrique].

    Cette API s’exécute dans l’espace de noms sn-api-notif-mgmt et nécessite le rôle sn_api_notif_mgmt.event_mgmt_integration.

    Rubrique Gestion des événements ouverte : PUBLIER /sn_api_notif_mgmt/rubrique

    Crée un nouvel enregistrement dans la table Rubrique [sn_api_notif_mgmt_topic] et enregistre les informations de rubrique transmises dans cet enregistrement.

    Utilisez ce point de terminaison pour synchroniser les rubriques créées dans votre intergiciel de bus de message avec celles de votre ServiceNow instance.

    Lorsque des rubriques sont créées à l’aide de ce point de terminaison, le champ user_created de l’enregistrement de rubrique associé est défini sur faux et le champ type est défini sur Sortie.

    Format d'URL

    URL versionnée : /api/sn_api_notif_mgmt/v1/topic

    URL par défaut : /api/sn_api_notif_mgmt/topic

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière.

    Type de données : chaîne
    Tableau 2. Paramètres de requête
    Nom Description
    Aucun
    Tableau 3. Paramètres du corps de la demande
    Nom Description
    contentQuery (en anglais seulement) Filtre à appliquer à la charge utile de l’événement. Cette requête est un filtre d’événement plus profond qui est utilisé pour trouver des informations telles que la gravité de l’événement ou le type de ticket. Vous pouvez transmettre ce paramètre en tant que requête imbriquée.
    Par exemple, pour la charge utile de l’événement de ticket de défaillance suivante, cette requête s’applique aux attributs qui se trouvent dans l’objet « event » de la charge utile :
    {
  "eventId":"dc2003c2c3bb3550054e20bdc0013136",
  "@type":"Troubleticket",
  "eventType":"TroubleTicketCreateEvent",
  "event":{
    "troubleTicket":{
      "short_description":"Test payload",
      "severity":3,
      "ticketType":"incident"
    }
  }
}
    Ce paramètre prend en charge les conditions suivantes :
    • ET : par exemple variable1=valeur1&variable2=valeur2&variable3=valeur3
    • OU : par exemple variable1=value1,value2,value3
    • Variables hiérarchiques : telles que variable1.variable2.variable3=valeur1

    Par exemple : « contentQuery » : « troubleTicket.ticketType=incident&troubleTicket.severity=1 »,

    Ce champ est mappé au champ content_query dans l’enregistrement de rubrique associé.

    Pour plus d’informations, consultez le Guide de l’utilisateur de l’API Gestion des événements TMF688.

    Type de données : chaîne
    externalId Identificateur externe unique pour la rubrique, tel qu’un GUID. Ce champ est mappé au champ topic_id dans l’enregistrement de rubrique associé.

    Type de données : chaîne
    headerQuery Filtre à appliquer aux propriétés de l’en-tête d’événement. Cette requête définit le type d’événements à écouter pour la rubrique associée. Vous pouvez transmettre ce paramètre en tant que requête imbriquée.
    Ce paramètre prend en charge les conditions suivantes :
    • ET : par exemple variable1=valeur1&variable2=valeur2&variable3=valeur3
    • OU : par exemple variable1=value1,value2,value3
    • Variables hiérarchiques : telles que variable1.variable2.variable3=valeur1

    Par exemple : « headerQuery » : « eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent »

    Ce champ est mappé au champ header_query dans l’enregistrement de rubrique associé.

    Pour plus d’informations, consultez le Guide de l’utilisateur de l’API Gestion des événements TMF688.

    Type de données : chaîne
    nom Nom de la rubrique.

    Ce champ est mappé au champ topic_name dans l’enregistrement de rubrique associé.

    Type de données : chaîne
    espace de noms Espace de noms pour la rubrique. Vide s’il n’y a pas d’espace de noms associé.

    Ce champ est mappé au champ d’espace de noms dans l’enregistrement de rubrique associé.

    Type de données : chaîne

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Prend uniquement en charge application/json.
    Content-Type Format de données du corps de la demande. Prend uniquement en charge application/json.
    Tableau 5. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 6. Codes d'état
    Code d'état Description
    201 Réussi. La demande a été correctement traitée.
    400 L’ID externe de rubrique transmis existe déjà. Veuillez transmettre l’ID externe de rubrique unique : indique que l’ID externe transmis existe déjà dans la table de rubriques.

    Veuillez transmettre la combinaison unique du nom de la rubrique, de la requête d’en-tête, de la requête de contenu et de l’espace de noms : indique que la combinaison du nom de la rubrique, de l’espace de noms, de la requête d’en-tête et de la requête de contenu existe déjà.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres du corps de réponse

    Nom Description
    contentQuery (en anglais seulement) Valeur du champ content_query dans l’enregistrement de rubrique créé.

    Type de données : chaîne
    externalId Valeur du champ topic_id dans l’enregistrement de rubrique créé.

    Type de données : chaîne
    headerQuery Valeur du champ header_query dans l’enregistrement de rubrique créé. Ce champ est utilisé par le cadre de travail du sélecteur de rubrique pour déterminer les messages d’événement qui doivent être envoyés à une rubrique.

    Type de données : chaîne
    id Sys_id de l’enregistrement de rubrique créé.

    Type de données : chaîne
    nom Nom de la rubrique.

    Type de données : chaîne
    espace de noms Valeur du champ d’espace de noms dans l’enregistrement de rubrique créé.

    Type de données : chaîne

    Demande cURL

    L’exemple de code suivant montre comment appeler ce point de terminaison.

    curl "http://instance.servicenow.com/api/sn_api_notif_mgmt/topic" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data
{
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "externalId": "ext001",
  "namespace": "telecomEvents"
}

    Réponse :

    
{
  "externalId": "ext001",
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "namespace": "telecomEvents",
  "id": "7ee9850443c3f550461f99612bb8f223"
}