Aperçu
Une intégration est une connexion configurée qui envoie des messages d’alerte d’Uptrends vers des systèmes externes, comme un e-mail, Slack, PagerDuty ou un webhook personnalisé.
Lorsqu’un moniteur détecte un problème, Uptrends utilise les intégrations liées dans vos définitions d’alerte pour transmettre des notifications aux opérateurs ou aux systèmes tiers.
Utilisez la Integration API pour gérer les intégrations par défaut, personnalisées ou tierces d’Uptrends dans votre compte.
Cas d’utilisation
- Récupérer les détails des intégrations pour suivre les alertes et le statut — listez les intégrations de votre compte, examinez la configuration, et vérifiez le type d’intégration et le statut actif.
- Gérer les intégrations par type :
- Créer, mettre à jour et supprimer des intégrations personnalisées
- Récupérer ou supprimer des intégrations tierces
- Récupérer les intégrations par défaut
- Contrôler l’accès pour les opérateurs et les groupes d’opérateurs
Prérequis
Avant d’utiliser la Integration API, assurez-vous de disposer des éléments suivants :
Endpoints de la Integration API
La Integration API expose les endpoints suivants pour gérer les informations d’intégration.
Intégrations
Utilisez les endpoints suivants pour gérer les intégrations par défaut (SMS, Email et Phone) et les intégrations tierces (Slack, PagerDuty et StatusHub).
| Méthode | Endpoint | Description |
|---|---|---|
GET |
/Integration |
Renvoie une liste de toutes les intégrations du compte. |
DELETE |
/Integration/{integrationGuid} |
Supprime l’intégration spécifiée. Les types d’intégration par défaut, notamment e-mail, téléphone et SMS, ne peuvent pas être supprimés. |
GET |
/Integration/{integrationGuid}/Authorizations |
Renvoie une liste des opérateurs et groupes d’opérateurs qui disposent d’autorisations d’accès à l’intégration. Si aucune autorisation n’est définie, le corps de la réponse renvoie une liste vide. |
POST |
/Integration/{integrationGuid}/Authorizations |
Crée des autorisations pour l’intégration spécifiée. L’octroi d’une autorisation inclut automatiquement toutes les autorisations dépendantes requises. Par exemple, l’octroi de l’autorisation EditIntegration accorde également UseIntegration. |
DELETE |
/Integration/{integrationGuid}/Authorizations/{authorizationGuid} |
Supprime l’autorisation spécifiée pour l’intégration. |
Intégrations personnalisées
Les intégrations personnalisées sont des intégrations tierces du type GenericWebhook. Vous pouvez récupérer leurs informations générales, comme l’ID d’intégration, le nom, le statut et le type, à l’aide de l’endpoint GET /Integration.
Pour récupérer et gérer les détails complets de configuration d’une intégration personnalisée, utilisez les endpoints Custom suivants.
Remarque
Seul l’endpoint
/Integration/Custompermet de créer et de mettre à jour l’intégration.
| Méthode | Endpoint | Description |
|---|---|---|
GET |
/Integration/Custom |
Renvoie une liste de toutes les intégrations personnalisées du compte. La réponse inclut le type d’intégration et, pour les intégrations personnalisées, une IntegrationDetailUrl qui pointe vers l’endpoint de détail propre au type. |
POST |
/Integration/Custom |
Crée une nouvelle intégration personnalisée. |
GET |
/Integration/Custom/{integrationGuid} |
Renvoie l’intégration personnalisée spécifiée. |
PUT |
/Integration/Custom/{integrationGuid} |
Met à jour l’intégration personnalisée spécifiée. |
DELETE |
/Integration/Custom/{integrationGuid} |
Supprime l’intégration personnalisée spécifiée. |
Pour les paramètres d’endpoint, les schémas de requête et de réponse, et les tests interactifs, utilisez la Uptrends Integration API.
Exemples d’API
Intégrations par défaut et tierces
Réponse GET
Exemple de corps de réponse GET /Integration :
[
{
"IntegrationGuid": "1a23b4e5-6f78-423f-8a1f-f2a8cc399f4b",
"Name": "Alerting by SMS",
"Type": "Sms",
"IsActive": true,
"DefaultSmsProvider": "SmsProviderInternational",
"DefaultUseNumericSender": false
},
{
"IntegrationGuid": "ab123c45-a28c-47b5-bbc8-645c3b93da59",
"Name": "Statuspage",
"Type": "GenericWebhook",
"IntegrationDetailUrl": "Integration/Custom/ab123c45-d28e-47b5-fgh8-645i3b93da59",
"IsActive": true
},
{
"IntegrationGuid": "12a345b6-d061-405f-9b48-c72f34461218",
"Name": "Alerting by email",
"Type": "Email",
"IsActive": true,
"UseHtmlMail": true,
"UseCustomEmailSubjectConfirmedError": false,
"UseCustomEmailSubjectConfirmedErrorPlural": false,
"UseCustomEmailSubjectReminderConfirmedError": false,
"UseCustomEmailSubjectReminderConfirmedErrorPlural": false,
"UseCustomEmailSubjectOK": false,
"UseCustomEmailSubjectOKPlural": false,
"EmailSubjectConfirmedError": "Uptrends Alert! Monitor: \"{{@monitor.name}}\" is not working properly.",
"EmailSubjectConfirmedErrorPlural": "Uptrends Alert! Multiple Monitors are not working properly: \"{{@monitor.name}}\".",
"EmailSubjectReminderConfirmedError": "Uptrends Reminder! Monitor: \"{{@monitor.name}}\" is still not working properly.",
"EmailSubjectReminderConfirmedErrorPlural": "Uptrends Reminder! Multiple Monitors are still not working properly: \"{{@monitor.name}}\".",
"EmailSubjectOK": "Uptrends Alert! Monitor: \"{{@monitor.name}}\" is OK.",
"EmailSubjectOKPlural": "Uptrends Alert! Multiple Monitors are now OK: \"{{@monitor.name}}\"."
}
]
Exemple de corps de réponse GET /Integration/{integrationGuid}/Authorizations :
{
"AuthorizationId": "12a348ce-385a-4316-9341-a0a22ff3cbcc",
"AuthorizationType": "UseIntegration",
"OperatorGroupGuid": "1234ab52-168e-4d54-bd1c-9e65226e82cb"
}
Intégrations personnalisées
Remarque
Les intégrations personnalisées reposent sur des modèles. La structure JSON exacte peut différer selon les implémentations. Le schéma présenté dans ce document représente une structure de référence, et non un schéma strict appliqué à toutes les intégrations.
Appelez GET /Integration et recherchez les intégrations dont Type est GenericWebhook.
Utilisez la valeur IntegrationDetailUrl comme référence lorsque vous appelez GET /Integration/Custom/. Vous pouvez également appeler directement GET /Integration/Custom/{integrationGuid} pour récupérer la configuration complète.
Ce qui suit montre un exemple de structure d’une réponse GET /Integration/Custom :
[
{
"IntegrationGuid": "ab123c45-a28c-47b5-bbc8-645c3b93da59",
"Name": "Statuspage",
"IsActive": true,
"Notes": "This integration updates the Statuspage component for Uptrends alert status.",
"HttpStepDefinitions": [
{
"HttpStepDefinitionUsageGuid": "ab1234c5-8427-489d-eda6-1923e17c870e",
"Steps": [
{
"Url": "https://api.example.io/v1/pages/{{PageId}}/components/{{ComponentId}}",
"Method": "PATCH",
"Body": "{\r\n \"component\": {\r\n \"status\": \"{{MapTypeToStatusPageStatus({{@alert.type}})}}\"\r\n }\r\n}",
"BodyType": "Raw",
"MultiPartForm": [],
"RequestHeaders": [
{
"Key": "Content-Type",
"Value": "application/json"
},
{
"Key": "Authorization",
"Value": "OAuth {{ApiKey}}"
}
],
"Variables": [
{
"Source": "ResponseBodyJson",
"Property": "[0].ProductId",
"Name": "ProductId",
"Arguments": []
}
],
"Assertions": [
{
"Source": "ResponseStatusCode",
"Property": "",
"Comparison": "Equal",
"TargetValue": "200"
}
],
"UseFixedClientCertificate": false,
"Authentication": {
"Id": "a123b5b6-3c59-4c9d-9335-587e68f3f58f",
"AuthenticationType": "None",
"UserName": "",
"PasswordSpecified": false
},
"IgnoreCertificateErrors": false,
"Delay": 0,
"StepType": "HttpRequest",
"RetryUntilSuccessful": false,
"MaxAttempts": 2,
"RetryWaitMilliseconds": 1000,
"PreRequestScript": "",
"PostResponseScript": "",
"CalculatedContentType": "",
"AllowedTlsVersions": []
}
],
"UserDefinedFunctions": [
{
"Name": "MapTypeToStatusPageStatus",
"Type": "Mapping",
"Mappings": [
{
"Key": "Ok",
"Value": "operational"
},
{
"Key": "Alert",
"Value": "major_outage"
}
]
}
],
"Usages": [
"Alert",
"Ok"
]
}
],
"IntegrationVariables": [
{
"Name": "ApiKey",
"Value": "a",
"IsValueSetInEscalationLevel": false
},
{
"Name": "PageId",
"Value": "b",
"IsValueSetInEscalationLevel": false
},
{
"Name": "ComponentId",
"Value": "c",
"IsValueSetInEscalationLevel": false
}
]
},
{
"IntegrationGuid": "8f7c9fd0-8473-40f2-88bd-6d9ccbf40434",
"Name": "Opsgenie",
"IsActive": true,
"Notes": "This integration sends alerts to Opsgenie.",
"HttpStepDefinitions": [
{
"HttpStepDefinitionUsageGuid": "1abcdef2-345g-496e-9d65-802686fc1245",
"Steps": [
{
"Url": "https://api.example.com/v2/alerts",
"Method": "POST",
"Body": "{\r\n \"message\": \"[Uptrends] {{@monitor.name}}\",\r\n \"alias\": \"{{@incident.key}}\",\r\n \"description\": \"{{@JsonEncode({{@alert.description}})}}\",\r\n \"details\": {\r\n \"alertGuid\": \"{{@alert.alertGuid}}\",\r\n \"type\": \"{{@alert.type}}\",\r\n \"timestampUtc\": \"{{@alert.timestampUtc}}\",\r\n \"timestamp\": \"{{@alert.timestamp}}\",\r\n \"firstErrorUtc\": \"{{@alert.firstErrorUtc}}\",\r\n \"firstError\": \"{{@alert.firstError}}\",\r\n \"firstErrorCheckUrl\": \"{{@alert.firstErrorCheckUrl}}\",\r\n \"firstErrorCheckId\": \"{{@alert.firstErrorCheckId}}\",\r\n \"serverIpv4\": \"{{@alert.serverIpv4}}\",\r\n \"serverIpv6\": \"{{@alert.serverIpv6}}\",\r\n \"numberOfConsecutiveErrors\": \"{{@alert.numberOfConsecutiveErrors}}\",\r\n \"checkpointName\": \"{{@alert.checkpointName}}\"\r\n },\r\n \"priority\": \"{{Priority}}\"\r\n}",
"BodyType": "Raw",
"MultiPartForm": [],
"RequestHeaders": [
{
"Key": "Content-Type",
"Value": "application/json"
},
{
"Key": "Authorization",
"Value": "GenieKey {{ApiKey}}"
}
],
"Variables": [
{
"Source": "ResponseBodyJson",
"Property": "[0].ProductId",
"Name": "ProductId",
"Arguments": []
}
],
"Assertions": [
{
"Source": "ResponseStatusCode",
"Property": "",
"Comparison": "Equal",
"TargetValue": "200"
}
],
"UseFixedClientCertificate": false,
"Authentication": {
"Id": "12a3b4c5-261c-4e90-a5c0-fa2b11bc54da",
"AuthenticationType": "None",
"UserName": "",
"PasswordSpecified": false
},
"IgnoreCertificateErrors": false,
"Delay": 0,
"StepType": "HttpRequest",
"RetryUntilSuccessful": false,
"MaxAttempts": 2,
"RetryWaitMilliseconds": 1000,
"PreRequestScript": "",
"PostResponseScript": "",
"CalculatedContentType": "",
"AllowedTlsVersions": []
}
],
"UserDefinedFunctions": [
{
"Name": "MapTypeToStatusPageStatus",
"Type": "Mapping",
"Mappings": [
{
"Key": "Ok",
"Value": "operational"
},
{
"Key": "Alert",
"Value": "major_outage"
}
]
}
],
"Usages": [
"Alert",
"Reminder"
]
}
],
"IntegrationVariables": [
{
"Name": "ApiKey",
"Value": "a",
"IsValueSetInEscalationLevel": false
},
{
"Name": "Priority",
"Value": "P1",
"IsValueSetInEscalationLevel": false
}
]
}
]
Requête POST et PUT
Utilisez la même structure pour les corps de requête POST /Integration/Custom et PUT /Integration/Custom/{integrationGuid}. Omettez IntegrationGuid lorsque vous créez une nouvelle intégration, car il est généré automatiquement.
Vous pouvez utiliser l’application web Uptrends comme point de départ pour créer une intégration personnalisée. Récupérez la configuration avec GET /Integration/Custom/{integrationGuid}, puis mettez-la à jour avec l’API.
{
"IntegrationGuid": "1c234567-846d-44b4-8991-b8eedc1c68c9",
"Name": "Uptrends Test API",
"IsActive": true,
"Notes": "This integration implementation contains a predefined (but customizable) JSON-formatted message containing the full range of available alerting parameters. ",
"HttpStepDefinitions": [
{
"HttpStepDefinitionUsageGuid": "ab1c9d38-a4ca-4a5b-926f-62228f7b5a68",
"Steps": [
{
"Url": "https://api-test.example.net/Account",
"Method": "GET",
"BodyType": "Raw",
"MultiPartForm": [
{
"Type": "VaultFile",
"Key": "file",
"Value": "b84daa9c-cdf3-4ba8-90fa-49aa70dc80c0"
}
],
"RequestHeaders": [
{
"Key": "Content-Type",
"Value": "application/json"
}
],
"Variables": [
{
"Source": "ResponseBodyJson",
"Property": "[0].ProductId",
"Name": "ProductId",
"Arguments": []
}
],
"Assertions": [
{
"Source": "ResponseStatusCode",
"Property": "",
"Comparison": "Equal",
"TargetValue": "200"
}
],
"UseFixedClientCertificate": false,
"Authentication": {
"Id": "12342229d-68cf-4328-b90c-ecb3094b9eac",
"AuthenticationType": "Basic",
"UserName": "{{Username}}",
"PasswordSpecified": false
},
"IgnoreCertificateErrors": false,
"Delay": 0,
"StepType": "HttpRequest",
"RetryUntilSuccessful": false,
"MaxAttempts": 2,
"RetryWaitMilliseconds": 1000,
"PreRequestScript": "",
"PostResponseScript": "",
"CalculatedContentType": "application/json",
"AllowedTlsVersions": []
}
],
"UserDefinedFunctions": [
{
"Name": "MapTypeToStatusPageStatus",
"Type": "Mapping",
"Mappings": [
{
"Key": "Ok",
"Value": "operational"
},
{
"Key": "Alert",
"Value": "major_outage"
}
]
}
],
"Usages": [
"Alert",
"Ok",
"Reminder"
]
}
],
"IntegrationVariables": [
{
"Name": "ApiUrl",
"Value": "https://example.site/1ab23bcde",
"IsValueSetInEscalationLevel": false
},
{
"Name": "Password",
"Value": "pass",
"IsValueSetInEscalationLevel": false
},
{
"Name": "Username",
"Value": "uname",
"IsValueSetInEscalationLevel": false
}
]
}
Paramètres d’API
| Nom du champ | Description |
|---|---|
integrationGuid |
Paramètre de chemin. Le GUID de l’intégration. |
authorizationGuid |
Paramètre de chemin. Le GUID de l’autorisation associée à l’intégration. |
Champs d’API généraux
Les ressources d’intégration utilisent les propriétés suivantes dans les corps de requête et de réponse :
| Nom du champ | Description |
|---|---|
IntegrationGuid |
L’identifiant unique de l’intégration. Attribué automatiquement lors de la création de l’intégration. |
Name |
Le nom de l’intégration. |
Type |
Le type d’intégration. Exemples :
Email, Sms, Phone et GenericWebhook. |
IsActive |
Lorsque la valeur est true, l’intégration est active. Sinon, l’intégration est inactive et n’est utilisée dans aucune définition d’alerte. |
IntegrationDetailUrl |
L’URL de l’endpoint de détail d’intégration propre au type, si disponible. |
Les champs supplémentaires ci-dessous peuvent également être disponibles selon le type d’intégration.
Champs d’intégration e-mail
Les champs suivants sont disponibles lorsque vous personnalisez une intégration e-mail :
| Nom du champ | Description |
|---|---|
ExtraEmailAddresses |
Adresses e-mail supplémentaires qui reçoivent les notifications d’alerte comme configuré dans le niveau d’escalade de la définition d’alerte. |
UseHtmlMail |
Lorsque la valeur est true, Uptrends envoie les e-mails d’alerte au format HTML, avec des liens cliquables et une mise en forme. Lorsque la valeur est false, les e-mails sont envoyés en texte brut. |
UseCustomEmailSubjectConfirmedError |
Lorsque la valeur est true, les alertes e-mail d’erreur confirmée utilisent un objet personnalisé. Lorsque la valeur est false, elles utilisent l’objet d’e-mail par défaut. |
UseCustomEmailSubjectConfirmedErrorPlural |
Lorsque la valeur est true, les alertes e-mail d’erreur confirmée pour plusieurs moniteurs utilisent un objet personnalisé. Lorsque la valeur est false, elles utilisent l’objet d’e-mail par défaut. |
UseCustomEmailSubjectReminderConfirmedError |
Lorsque la valeur est true, les rappels par e-mail pour les erreurs confirmées utilisent un objet personnalisé. Lorsque la valeur est false, ils utilisent l’objet d’e-mail par défaut. |
UseCustomEmailSubjectReminderConfirmedErrorPlural |
Lorsque la valeur est true, les rappels par e-mail pour plusieurs moniteurs avec des erreurs confirmées utilisent un objet personnalisé. Lorsque la valeur est false, ils utilisent l’objet d’e-mail par défaut. |
UseCustomEmailSubjectOK |
Lorsque la valeur est true, les alertes e-mail OK utilisent un objet personnalisé. Lorsque la valeur est false, elles utilisent l’objet d’e-mail par défaut. |
UseCustomEmailSubjectOKPlural |
Lorsque la valeur est true, les alertes e-mail OK pour plusieurs moniteurs utilisent un objet personnalisé. Lorsque la valeur est false, elles utilisent l’objet d’e-mail par défaut. |
EmailSubjectConfirmedError |
L’objet d’e-mail personnalisé utilisé pour les alertes d’erreur confirmée. |
EmailSubjectConfirmedErrorPlural |
L’objet d’e-mail personnalisé utilisé pour les alertes d’erreur confirmée concernant plusieurs moniteurs. |
EmailSubjectReminderConfirmedError |
L’objet d’e-mail personnalisé utilisé pour les alertes de rappel concernant les erreurs confirmées. |
EmailSubjectReminderConfirmedErrorPlural |
L’objet d’e-mail personnalisé utilisé pour les alertes de rappel concernant les erreurs confirmées pour plusieurs moniteurs. |
EmailSubjectOK |
L’objet d’e-mail personnalisé utilisé pour les alertes OK. |
EmailSubjectOKPlural |
L’objet d’e-mail personnalisé utilisé pour les alertes OK concernant plusieurs moniteurs. |
Champs d’intégration SMS
| Nom du champ | Description |
|---|---|
DefaultSmsProvider |
Le fournisseur SMS utilisé pour envoyer les messages texte d’alerte :
|
DefaultUseNumericSender |
Lorsque la valeur est true, Uptrends utilise un ID d’expéditeur numérique. Lorsque la valeur est false, il utilise l’ID d’expéditeur textuel par défaut (par exemple, Uptrends). |
Champs d’intégration téléphone
| Nom du champ | Description |
|---|---|
DefaultOutgoingPhoneNumber |
Le numéro de téléphone sortant pour passer des appels d’alerte :
Pour en savoir plus, consultez la OutgoingPhoneNumber API. |
PhoneMessageCulture |
La langue utilisée par l’opérateur téléphonique lorsque vous recevez l’appel. Les langues prises en charge sont :
|
UseSpeechFriendlyMonitorNames |
Lorsque la valeur est
true, l’opérateur téléphonique utilise dans les appels téléphoniques les noms de moniteur alternatifs définis dans l’onglet Principal de votre éditeur de moniteurs. Pour en savoir plus, consultez noms de moniteurs adaptés à la synthèse vocale. |
Champs d’intégration personnalisée
Les champs d’intégration personnalisée définissent la configuration d’envoi des messages d’alerte pour les types d’alerte Error, OK et Reminder. Chaque type d’alerte utilise des définitions d’étape HTTP qui contrôlent le comportement des requêtes et des réponses, notamment le contenu des messages et les étapes de workflow supplémentaires, comme l’authentification et les fonctions définies par l’utilisateur.
| Nom du champ | Description |
|---|---|
Notes |
Champ de texte libre permettant d’ajouter des commentaires internes ou des détails sur l’intégration personnalisée. |
HttpStepDefinitions |
Définit la structure HTTP de l’intégration personnalisée. Principaux champs imbriqués :
|
IntegrationVariables |
Variables utilisées dans l’intégration pour les identifiants ou les valeurs réutilisables. |
Autres champs d’API
Champs d’API propres à certaines intégrations, notamment StatusHub et PagerDuty.
| Nom du champ | Description |
|---|---|
IntegrationServices |
S’applique à l’intégration StatusHub. Liste des ID de services d’intégration associés à l’intégration. |
IntegrationServiceGuid |
L’identifiant unique d’un service d’intégration StatusHub. |
StatusHubServiceList |
S’applique à l’intégration StatusHub. Liste des services Status Hub, notamment MonitorGuid et IntegrationServiceGuid. |
UseSilentMode |
S’applique à l’intégration StatusHub. Lorsque la valeur est true, l’intégration consigne uniquement les mises à jour dans la page de statut. Lorsque la valeur est false, les utilisateurs reçoivent une notification d’alerte concernant les mises à jour. |
IntegrationKey |
S’applique à l’intégration PagerDuty. La clé d’intégration. Renvoyée uniquement lorsque l’utilisateur authentifié dispose d’une autorisation de modification sur l’intégration. |
Champs d’autorisation
| Nom du champ | Description |
|---|---|
AuthorizationId |
L’ID unique de l’autorisation. |
AuthorizationType |
Le type d’autorisation associé à l’intégration. Les options incluent :
|
Dépannage
Cette section couvre les erreurs HTTP courantes et les étapes de dépannage pour la Integration API.
Erreurs courantes
Codes de statut HTTP courants et leurs descriptions :
| Code de statut | Description |
|---|---|
| 200 | OK — requête réussie. |
| 201 | Created — la ressource a été créée avec succès (par exemple, une intégration personnalisée ou une autorisation). |
| 204 | No content — la requête s’est terminée avec succès et aucun corps de réponse n’a été renvoyé. Cela s’applique aux requêtes PUT et DELETE réussies. |
| 400 | Bad request — paramètres de requête non valides ou champs obligatoires manquants. |
| 401 | Unauthorized — identifiants d’authentification non valides ou manquants. |
| 403 | Forbidden — une ou plusieurs erreurs de validation se sont produites. Cela peut être lié aux autorisations du compte. |
| 404 | Not Found — le authorizationGuid ou integrationGuid spécifié est introuvable. |
| 500 | Internal Server Error — une erreur côté serveur s’est produite. |
Guide général de dépannage
Assurez-vous de :
- Toujours valider vos données de requête avant d’envoyer des appels API.
- Utiliser les méthodes HTTP appropriées pour chaque opération.
Pour obtenir de l’aide supplémentaire, veuillez contacter notre équipe de support.
Articles associés
Pour en savoir plus, consultez les articles suivants :
- documentation de la Uptrends Integration API — documentation API interactive avec des spécifications d’endpoint détaillées.
- changelog API — dernières mises à jour de l’API et avis d’obsolescence.