Overzicht
Een integratie is een geconfigureerde verbinding die alertberichten van Uptrends naar externe systemen stuurt, zoals e-mail, Slack, PagerDuty of een aangepaste webhook.
Wanneer een monitor een probleem detecteert, gebruikt Uptrends de integraties die in uw alertdefinities zijn gekoppeld om meldingen af te leveren bij operators of third-partysystemen.
Gebruik de Integration API om standaardintegraties, aangepaste integraties of third-party-integraties van Uptrends in uw account te beheren.
Use cases
- Haal integratiedetails op om alerting en status bij te houden — geef integraties in uw account weer, controleer de configuratie en controleer het integratietype en de actieve status.
- Beheer integraties op type:
- Aangepaste integraties creëren, bijwerken en verwijderen
- Third-party-integraties ophalen of verwijderen
- Standaardintegraties ophalen
- Toegang beheren voor operators en operatorgroepen
Vereisten
Voordat u de Integration API gebruikt, moet u ervoor zorgen dat u beschikt over:
Integration API-eindpunten
De Integration API biedt de volgende eindpunten voor het beheren van integratie-informatie.
Integraties
Gebruik de volgende eindpunten om standaardintegraties (SMS, E-mail en Telefoon) en third-party-integraties (Slack, PagerDuty en StatusHub) te beheren.
| Methode | Eindpunt | Beschrijving |
|---|---|---|
GET |
/Integration |
Retourneert een lijst met alle integraties in het account. |
DELETE |
/Integration/{integrationGuid} |
Verwijdert de opgegeven integratie. Standaardintegratietypes, waaronder e-mail, telefoon en SMS, kunnen niet worden verwijderd. |
GET |
/Integration/{integrationGuid}/Authorizations |
Retourneert een lijst met operators en operatorgroepen die toegangsrechten voor de integratie hebben. Als er geen autorisaties zijn ingesteld, retourneert de responsbody een lege lijst. |
POST |
/Integration/{integrationGuid}/Authorizations |
Creëert autorisaties voor de opgegeven integratie. Het verlenen van een recht omvat automatisch alle vereiste afhankelijke rechten. Als u bijvoorbeeld het recht EditIntegration verleent, wordt ook UseIntegration verleend. |
DELETE |
/Integration/{integrationGuid}/Authorizations/{authorizationGuid} |
Verwijdert het opgegeven recht voor de integratie. |
Aangepaste integraties
Aangepaste integraties zijn third-party-integraties van het type GenericWebhook. U kunt de algemene informatie ervan ophalen, zoals integratie-ID, naam, status en type, met het eindpunt GET /Integration.
Gebruik de volgende Custom-eindpunten om de volledige configuratiedetails van een aangepaste integratie op te halen en te beheren.
Opmerking
Alleen met het eindpunt
/Integration/Customkunt u de integratie creëren en bijwerken.
| Methode | Eindpunt | Beschrijving |
|---|---|---|
GET |
/Integration/Custom |
Retourneert een lijst met alle aangepaste integraties in het account. De respons bevat het integratietype en, voor aangepaste integraties, een IntegrationDetailUrl die naar het typespecifieke detaileindpunt verwijst. |
POST |
/Integration/Custom |
Creëert een nieuwe aangepaste integratie. |
GET |
/Integration/Custom/{integrationGuid} |
Retourneert de opgegeven aangepaste integratie. |
PUT |
/Integration/Custom/{integrationGuid} |
Werkt de opgegeven aangepaste integratie bij. |
DELETE |
/Integration/Custom/{integrationGuid} |
Verwijdert de opgegeven aangepaste integratie. |
Gebruik de Uptrends Integration API voor eindpuntparameters, request- en responseschema’s en interactief testen.
API-voorbeelden
Standaardintegraties en third-party-integraties
GET-respons
Voorbeeld van een GET /Integration-responsbody:
[
{
"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}}\"."
}
]
Voorbeeld van een GET /Integration/{integrationGuid}/Authorizations-responsbody:
{
"AuthorizationId": "12a348ce-385a-4316-9341-a0a22ff3cbcc",
"AuthorizationType": "UseIntegration",
"OperatorGroupGuid": "1234ab52-168e-4d54-bd1c-9e65226e82cb"
}
Aangepaste integraties
Opmerking
Aangepaste integraties zijn gebaseerd op sjablonen. De exacte JSON-structuur kan verschillen op basis van de implementaties. Het schema dat in dit document wordt getoond, vertegenwoordigt een referentiestructuur, geen strikt schema dat voor alle integraties wordt afgedwongen.
Roep GET /Integration aan en zoek integraties waarbij Type GenericWebhook is.
Gebruik de waarde IntegrationDetailUrl als referentie wanneer u GET /Integration/Custom/ aanroept. U kunt ook GET /Integration/Custom/{integrationGuid} rechtstreeks aanroepen om de volledige configuratie op te halen.
Het volgende toont een voorbeeldstructuur van een GET /Integration/Custom-respons:
[
{
"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
}
]
}
]
POST- en PUT-verzoek
Gebruik dezelfde structuur voor POST /Integration/Custom- en PUT /Integration/Custom/{integrationGuid}-requestbody’s. Laat IntegrationGuid weg wanneer u een nieuwe integratie creëert, omdat deze automatisch wordt gegenereerd.
U kunt de Uptrends-webapplicatie als uitgangspunt gebruiken om een aangepaste integratie te creëren. Haal de configuratie op met GET /Integration/Custom/{integrationGuid} en werk deze daarna bij met de 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
}
]
}
API-parameters
| Veldnaam | Beschrijving |
|---|---|
integrationGuid |
Padparameter. De GUID van de integratie. |
authorizationGuid |
Padparameter. De GUID van het recht dat aan de integratie is gekoppeld. |
Algemene API-velden
Integratie-resources gebruiken de volgende eigenschappen in request- en responsbody’s:
| Veldnaam | Beschrijving |
|---|---|
IntegrationGuid |
De unieke identifier van de integratie. Automatisch toegewezen wanneer de integratie wordt gecreëerd. |
Name |
De naam van de integratie. |
Type |
Het integratietype. Voorbeelden zijn
Email, Sms, Phone en GenericWebhook. |
IsActive |
Wanneer true, is de integratie actief. Anders is de integratie inactief en wordt deze in geen enkele alertdefinitie gebruikt. |
IntegrationDetailUrl |
De URL naar het typespecifieke integratiedetaileindpunt, indien beschikbaar. |
Aanvullende velden hieronder kunnen ook beschikbaar zijn op basis van het integratietype.
Velden voor e-mailintegratie
De volgende velden zijn beschikbaar wanneer u een e-mailintegratie aanpast:
| Veldnaam | Beschrijving |
|---|---|
ExtraEmailAddresses |
Aanvullende e-mailadressen die alertmeldingen ontvangen zoals geconfigureerd in het escalatieniveau van de alertdefinitie. |
UseHtmlMail |
Wanneer true, verstuurt Uptrends alert-e-mails in HTML-indeling, inclusief klikbare links en opmaak. Wanneer false, worden e-mails als platte tekst verstuurd. |
UseCustomEmailSubjectConfirmedError |
Wanneer true, gebruiken e-mailalerts voor bevestigde fouten een aangepast onderwerp. Wanneer false, gebruiken ze het standaard e-mailonderwerp. |
UseCustomEmailSubjectConfirmedErrorPlural |
Wanneer true, gebruiken e-mailalerts voor bevestigde fouten voor meerdere monitors een aangepast onderwerp. Wanneer false, gebruiken ze het standaard e-mailonderwerp. |
UseCustomEmailSubjectReminderConfirmedError |
Wanneer true, gebruiken e-mailherinneringen voor bevestigde fouten een aangepast onderwerp. Wanneer false, gebruiken ze het standaard e-mailonderwerp. |
UseCustomEmailSubjectReminderConfirmedErrorPlural |
Wanneer true, gebruiken e-mailherinneringen voor meerdere monitors met bevestigde fouten een aangepast onderwerp. Wanneer false, gebruiken ze het standaard e-mailonderwerp. |
UseCustomEmailSubjectOK |
Wanneer true, gebruiken OK-e-mailalerts een aangepast onderwerp. Wanneer false, gebruiken ze het standaard e-mailonderwerp. |
UseCustomEmailSubjectOKPlural |
Wanneer true, gebruiken OK-e-mailalerts voor meerdere monitors een aangepast onderwerp. Wanneer false, gebruiken ze het standaard e-mailonderwerp. |
EmailSubjectConfirmedError |
Het aangepaste e-mailonderwerp dat wordt gebruikt voor alerts voor bevestigde fouten. |
EmailSubjectConfirmedErrorPlural |
Het aangepaste e-mailonderwerp dat wordt gebruikt voor alerts voor bevestigde fouten voor meerdere monitors. |
EmailSubjectReminderConfirmedError |
Het aangepaste e-mailonderwerp dat wordt gebruikt voor herinneringsalerts voor bevestigde fouten. |
EmailSubjectReminderConfirmedErrorPlural |
Het aangepaste e-mailonderwerp dat wordt gebruikt voor herinneringsalerts voor bevestigde fouten voor meerdere monitors. |
EmailSubjectOK |
Het aangepaste e-mailonderwerp dat wordt gebruikt voor OK-alerts. |
EmailSubjectOKPlural |
Het aangepaste e-mailonderwerp dat wordt gebruikt voor OK-alerts voor meerdere monitors. |
Velden voor SMS-integratie
| Veldnaam | Beschrijving |
|---|---|
DefaultSmsProvider |
De SMS-provider die wordt gebruikt voor het versturen van alert-sms-berichten:
|
DefaultUseNumericSender |
Wanneer true, gebruikt Uptrends een numerieke afzender-ID. Wanneer false, gebruikt het de standaard tekstuele afzender-ID (bijvoorbeeld Uptrends). |
Velden voor telefoonintegratie
| Veldnaam | Beschrijving |
|---|---|
DefaultOutgoingPhoneNumber |
Het uitgaande telefoonnummer om alertoproepen te plaatsen:
Zie OutgoingPhoneNumber API voor meer informatie. |
PhoneMessageCulture |
De taal die de telefonische operator gebruikt wanneer u de oproep ontvangt. Ondersteunde talen zijn:
|
UseSpeechFriendlyMonitorNames |
Wanneer
true, gebruikt de telefonische operator in telefoongesprekken de alternatieve monitornamen die zijn ingesteld in het tabblad Algemeen van uw Monitor Editor. Zie spraakvriendelijke monitornamen voor meer informatie. |
Velden voor aangepaste integratie
Velden voor aangepaste integratie definiëren de configuratie voor het versturen van alertberichten voor de alerttypen Fout, OK en Herinnering. Elk alerttype gebruikt HTTP-stapdefinities die het request- en responsegedrag bepalen, inclusief berichtinhoud en aanvullende workflowstappen, zoals authenticatie en door de gebruiker gedefinieerde functies.
| Veldnaam | Beschrijving |
|---|---|
Notes |
Vrijetekstveld voor het toevoegen van interne opmerkingen of details over de aangepaste integratie. |
HttpStepDefinitions |
Definieert de HTTP-structuur van de aangepaste integratie. Belangrijke geneste velden:
|
IntegrationVariables |
Variabelen die in de integratie worden gebruikt voor inloggegevens of herbruikbare waarden. |
Overige API-velden
API-velden die specifiek zijn voor specifieke integraties, waaronder StatusHub en PagerDuty.
| Veldnaam | Beschrijving |
|---|---|
IntegrationServices |
Van toepassing op StatusHub-integratie. Lijst met integratieservice-ID’s die aan de integratie zijn gekoppeld. |
IntegrationServiceGuid |
De unieke identifier van een StatusHub-integratieservice. |
StatusHubServiceList |
Van toepassing op StatusHub-integratie. Lijst met Status Hub-services, inclusief de MonitorGuid en IntegrationServiceGuid. |
UseSilentMode |
Van toepassing op StatusHub-integratie. Wanneer true, registreert de integratie alleen de updates op de statuspagina. Wanneer false, ontvangen gebruikers een alertmelding over de updates. |
IntegrationKey |
Van toepassing op PagerDuty-integratie. De integratiesleutel. Wordt alleen geretourneerd wanneer de geauthenticeerde gebruiker bewerkingsrechten voor de integratie heeft. |
Autorisatievelden
| Veldnaam | Beschrijving |
|---|---|
AuthorizationId |
De unieke id van de autorisatie. |
AuthorizationType |
Het rechtentype dat aan de integratie is gekoppeld. Opties zijn onder andere:
|
Problemen oplossen
Deze sectie behandelt veelvoorkomende HTTP-fouten en stappen voor het oplossen van problemen voor de Integration API.
Veelvoorkomende fouten
Veelvoorkomende HTTP-statuscodes en hun beschrijvingen:
| Statuscode | Beschrijving |
|---|---|
| 200 | OK — verzoek geslaagd. |
| 201 | Created — de resource is met succes gecreëerd (bijvoorbeeld een aangepaste integratie of autorisatie). |
| 204 | No content — het verzoek is met succes voltooid en er is geen responsbody geretourneerd. Dit is van toepassing op geslaagde PUT- en DELETE-verzoeken. |
| 400 | Bad request — ongeldige verzoekparameters of ontbrekende verplichte velden. |
| 401 | Unauthorized — ongeldige of ontbrekende authenticatiegegevens. |
| 403 | Forbidden — er zijn een of meer validatiefouten opgetreden. Dit kan verband houden met accountrechten. |
| 404 | Not Found — de opgegeven authorizationGuid of integrationGuid is niet gevonden. |
| 500 | Internal Server Error — er is een server-side fout opgetreden. |
Algemene gids voor probleemoplossing
Zorg ervoor dat u:
- Uw verzoekgegevens altijd valideert voordat u API-calls verstuurt.
- Geschikte HTTP-methoden gebruikt voor elke bewerking.
Neem voor verdere hulp contact op met ons Support-team.
Gerelateerde artikelen
Raadpleeg de volgende artikelen voor meer informatie:
- Uptrends Integration API-documentatie — interactieve API-documentatie met gedetailleerde eindpuntspecificaties.
- API-changelog — nieuwste API-updates en deprecation-kennisgevingen.