1. Support
  2. Base de connaissances
  3. API d'Uptrends
  4. Uptrends API v3

API version 3

Nous changeons notre interface. Certaines informations peuvent ne pas être à jour. En savoir plus.

L’API Uptrends vous permet de modifier les informations des moniteurs et des groupes de moniteur directement dans votre compte Uptrends. L’API est un service web qui utilise une interface REST pour effectuer des Operations basiques de type CRUD (Create, Read, Update, Delete) sur des entités Uptrends.

Il vous permet également de récupérer les données de votre compte. Cela comprend l’état actuel de vos moniteurs, les statistiques de performance de vos moniteurs et groupes de moniteurs et l’historique des alertes de vos moniteurs.

La version 3 de l’API est une version ancienne ; l’utilisation de la version 4 est recommandée. En savoir plus sur les versions dans l’article de la base de connaissances Les API Uptrends.

Conditions préalables

Pour utiliser l’API Uptrends vous avez besoin de :

  1. Le nom d’utilisateur et le mot de passe d’un compte Uptrends, ou les informations de connexion d’un opérateur dans ce compte.
  2. L’accès au domaine de l’API à l’adresse : https://api.uptrends.com/v3

Accès à l’API

L’accès à l’API se fait avec le protocole HTTPS à l’adresse de l’URL spécifié.

Authentification

L’API nécessite l’authentification HTTP de base pour obtenir l’accès à l’information. Vous avez besoin d’un nom d’utilisateur et d’un mot de passe Uptrends pour obtenir l’accès.

Le nom d’utilisateur que vous utilisez peut être celui de votre compte Uptrends, ou celui de tout opérateur de votre compte. Notez qu’il vous faut utiliser un compte administrateur (un opérateur qui est membre du groupe d’administrateurs) si vous voulez effectuer des mises à jour.

Méthodes HTTP

Les actions suivantes, basées sur la méthode HTTP, sont prises en charge :

Operation Comments Http Return Code
GET Retrieve an item 200 (HTTP OK)
POST Create an item 201 (HTTP CREATED)
PUT Update an item 200 (HTTP OK)
DELETE Remove an item 200 (HTTP OK)

La gestion des erreurs

Lorsqu’une erreur se produit, un code d’erreur HTTP 400 (Bad Request) est retourné avec une description de l’erreur dans le contenu de la réponse.

L’API prend en charge le transfert des données dans les formats suivants :

Data formatHttp Content-typeOverride URL parameter
XMLapplication/xml?format=xml
JSONapplication/json?format=json
To embed the response in a jsonp callback append ?callback=myCallback
JSVtext/jsv?format=jsv
CSVtext/csv?format=csv
SOAP 1.1application/xml?format=soap11
SOAP 1.2application/xml?format=soap12

Format

Certaines Operations d’API renvoient des données DateTime. Le format de ces données sera conforme à la norme ISO 8601, mais sans informations de fuseau horaire. Les données seront exprimées en date et heure local, par rapport au fuseau horaire qui a été défini dans les paramètres de compte Uptrends.

Example :

La date et l’heure du 1er Juin, 2015 21:35:59 seront exprimées ainsi :
2015-06-01T21:35:59

indépendamment du fuseau horaire dans vos paramètres de compte. Si votre fuseau horaire est celui de Paris (UTC+01:00), cette valeur doit être interprétée comme le 1er Juin, 2015 21:35:50.

Les Operations de l’API

Toutes les Operations peuvent se faire sur la base de l’URL suivant :

URL de base : https://api.uptrends.com/v3/<operation url>

Le corps de la requête devrait contenir des données JSON ou XML avec le contenu suivant :

{"Name":"Updated ProbeGroupName"}

Pour les mises à jour, il suffit de renseigner seulement les champs à modifier. Les champs laissés vides de la requête ne seront pas modifiés.

Operations de moniteur

Operation Method URL Return value

Champ défini** : ** Probe

Field nameTypeComments
GuidGuidUnique monitor ID
NameStringName of the monitor
URLStringURL or IP address of the website, (web/database/mail/FTP/DNS-) server to check.
PortIntegerPort number
CheckFrequencyIntegerTime interval between individual checks, in minutes. Typically this is set to 5. Using a value lower than the minimum frequency for the account (also typically 5) returns an error.
ProbeTypeEnumerationAllowed values: Http, Https, Connect, Ping, POP3, SMTP, IMAP, FTP, MySQL, MSSQL, WebserviceHttp, WebserviceHttps, DNS, FullPageCheck, RealBrowserCheck
Note: the monitor type Transaction is not supported.
IsActiveBooleanIndicates whether the monitor is active. Inactive monitors are not measured. Allowed values: True, False
GenerateAlertBooleanIndicates whether to send alerts for this monitor. Allowed values: True, False
NotesStringUser-defined notes. This value is only displayed in the Uptrends application.
PerformanceLimit1IntegerFirst load time limit in milliseconds.
PerformanceLimit2IntegerSecond load time limit in milliseconds.
ErrorOnLimit1BooleanIndicates whether to generate errors when PerformanceLimit1 is exceeded. Allowed values: True, False
ErrorOnLimit2BooleanIndicates whether to generate errors when PerformanceLimit2 is exceeded. Allowed values: True, False
MinBytesIntegerThe minimum number of bytes in the server response to check for.
ErrorOnMinBytesBooleanIndicates whether to generate errors when MinBytes is exceeded. Allowed values: True, False
TimeoutIntegerThe time limit for the complete test, in milliseconds.
TcpConnectTimeoutIntegerThe time limit for the initial TCP connection, in milliseconds.
MatchPatternStringContent to check for in the response of HTTP requests. Regular expressions are allowed.
DnsLookupModeEnumerationHow to resolve the domain name specified in the URL field. Allowed values: Local (use the checkpoint’s own DNS), Primary (use the domain’s primary DNS server).
UserAgentStringThe user agent (browser identification value) to specify for HTTP(S), Real Browser Check and Full Page Check monitors.
UserNameStringThe username to specify as Basic/Digest/NTLM Authentication (when available), or the login name for FTP, FTPS or SQL monitors.
PasswordStringThe password to specify as Basic/Digest/NTLM Authentication (when available), or the password for FTP, FTPS or SQL monitors. Please note that the password field will always be empty when you retrieve data - you can only use this field when you specify a password.
CheckpointsStringAn enumeration of checkpoints to use for this monitor. To use all checkpoints, specify an empty value. To use specific checkpoints, list the checkpoint IDs separated by a comma, e.g.: 1,2,15,27 Note: when specifying specific checkpoints, select at least two checkpoints.
UseOnlyPrimaryCheckpointsBooleanIndicates whether Uptrends should limit the checkpoints you specify to primary checkpoints only. Uptrends defaults to True to limit the checkpoints to primary. To allow your monitor to run on non-primary checkpoint locations as well, specify False.
Please note: Due to technical limitations and other circumstances beyond Uptrends' control, non-primary checkpoints may suffer from reduced availability, poor bandwidth, and unpredictable connectivity. Please use this option only if you explicitly need monitoring from these locations and can accept results that are not always consistent.
Specific values for DNS monitors:
DNSQueryTypeEnumerationThe type of DNS query. Allowed values: ARecord, CNAMERecord, MXRecord, NSRecord, TXTRecord
DNSTestValueStringThe value to query for a DNS monitor. For example, when checking an A record, this value contains the domain name to check.
DNSExpectedResultStringThe expected result of the DNS query. Regular expressions are allowed.
Specific values for Database monitors:
DatabaseNameString
Specific values for HTTP(S) and WebserviceHTTP(S) monitors:
HttpMethodEnumerationAllowed values: Get, Post
PostDataStringContent for the request body in case of a Post request.
Specific values for Connect monitors:
ConnectMethodEnumerationAllowed values: Tcp, Udp

Exemple

Pour ajouter un moniteur de DNS au compte, envoyez une requête POST à https://api.uptrends.com/v3/probes, en fournissant l’authentification nécessaire, définissez les entêtes Content-Type et Accept à application/json et mettez le contenu suivant dans le corps de la requête :

{ "Name":"DNS Test monitor", "URL":"NS81.WORLDNIC.com", "Port":53, "CheckFrequency":5, "ProbeType":"DNS", "IsActive":true, "GenerateAlert":false, "Notes":"", "PerformanceLimit1":2500, "PerformanceLimit2":5000, "ErrorOnLimit1":false, "ErrorOnLimit2":false, "Timeout":30000, "TcpConnectTimeout":10000, "DnsLookupMode":"Local", "IsCompetitor":false, "Checkpoints":"1,8,28", "DNSQueryType":"MXRecord", "DNSTestValue":"uptrends.com", "DNSExpectedResult":"smtp.uptrends.com" }

Operations sur les groupes de moniteurs

Operation Method URL Return value
List all monitor groups GET /probegroups List<ProbeGroup>
Create monitor group POST /probegroups ProbeGroup
Get monitor group GET /probegroups/{ProbeGroupGuid} ProbeGroup
Update monitor group PUT /probegroups/{ProbeGroupGuid} (empty)
Delete monitor group DELETE /probegroups/{ProbeGroupGuid} (empty)

Champ défini **: ** ProbeGroup

Field name Type Comments
Guid Guid Unique monitor group ID
Name String Name of the monitor group

Exemple 1

Pour obtenir une liste de tous les groupes de moniteurs, envoyez une requête GET à /probegroups. Le corps de la réponse contient une liste des groupes de moniteurs :

[ { "Guid" : "680a5071c6d645a3b56945053b2d6a90", "Name" : "All probes" }, { "Guid" : "b1d9f5451aa04600992dc02d36f80e40", "Name" : "Probe group 1" }, { "Guid" : "25532138344a407597ad679ba1176aae", "Name" : "My other probe group" }, { "Guid" : "939110bb5d514dfe95e553b8a7dc8cde", "Name" : "Test probe group" } ]

Exemple 2

Pour créer un nouveau groupe, envoyez une requête POST à /probegroups. Le corps de la requête doit préciser le nom du nouveau groupe :

{"Name":"My new group"}

Le corps de la réponse contiendra le nouveau groupe :

{"Guid":"bd6e2c7e8a2348dc88206460d73f3658","Name":" My new group "}

Operations sur les membres des groupes de moniteurs

Les méthodes suivantes concernent l’appartenance à un groupe de moniteurs, c’est-à-dire quels moniteurs se trouvent dans quels groupes.

Operation Method URL Return value
List all monitors in a group GET /probegroups/{ProbeGroupGuid}/members List<Probe>
Add monitor to a group POST /probegroups/{ProbeGroupGuid}/members {Guid, ProbeGuid}
Remove monitor from a group DELETE /probegroups/{ProbeGroupGuid}/members (empty)

Exemple 1

Pour obtenir tous les moniteurs appartenant à un groupe de moniteurs, envoyez une requête GET à /probegroups/{ProbeGroupGuid}/members. Le corps de la réponse contiendra une liste des moniteurs (les données dans cet exemple ont été abrégées pour brièveté) :

[ { "Guid" : "f1248efda52e4d8db6ac6431a4a19177", "Name" : "Test probe 1", "URL" : "https://www.uptrends.com", "Port" : 80, }, { "Guid" : "a339b142-5a87-4a18-a718-00d679a13f5d", "Name" : "Test probe 2", "URL" : "https://www.uptrends.com", "Port" : 443, } ]

Exemple 2

Pour ajouter un moniteur à un groupe, envoyez une requête POST à /probegroups/{ProbeGroupGuid}/members. Le corps de la requête doit contenir le Guid du moniteur à ajouter au groupe :

{ "ProbeGuid" : "c4c8f5df7d02410bb1a837ce24bb2e8b" }

Obtenir une liste des serveurs de point de contrôle

L’opération suivante renvoie une liste des serveurs de point de contrôle d’Uptrends. Cette information peut être utilisée pour deux choses :

  1. Les valeurs de CheckpointID doivent être utilisées lorsqu’il faut spécifier des points de contrôle pour un moniteur.
  2. La liste contient les adresses IP pour chaque serveur de point de contrôle. Notez qu’un point de contrôle peut avoir plusieurs serveurs de contrôle, et donc des adresses IP multiples.
Operation Method URL Return value
List all checkpoint servers GET /checkpointservers List<CheckpointServer>

Champ défini : CheckpointServer

Field name Type Comments
CheckPointID Integer Unique ID for the checkpoint. Use this value for specifying checkpoints for a monitor.
ServerID Integer Only used to make the combination of CheckPointID and IP address unique. Do not use this value.
CheckPointName String Contains the city and country where the checkpoint server is located.
IPAddress String The IP address of the checkpoint server.

Exemple

Pour obtenir la liste des serveurs de point de contrôle, envoyez une requête GET à /checkpointservers. Le corps de la réponse contient une liste des points de contrôle (les données dans cet exemple ont été abrégées pour brièveté). Notez que le point de contrôle de Londres dans cet exemple (CheckpointID = 1) a deux adresses IP.

[ { "ServerID" : 0, "CheckPointID" : 0, "CheckPointName" : "Amsterdam, The Netherlands", "IPAddress" : "81.18.240.134" }, { "ServerID" : 10, "CheckPointID" : 1, "CheckPointName" : "London, United Kingdom", "IPAddress" : "81.89.133.149" }, { "ServerID" : 11, "CheckPointID" : 1, "CheckPointName" : "London, United Kingdom", "IPAddress" : "109.73.162.168" }, { "ServerID" : 20, "CheckPointID" : 2, "CheckPointName" : "Austin, TX, USA", "IPAddress" : "216.139.219.45" }, { "ServerID" : 30, "CheckPointID" : 3, "CheckPointName" : "Sydney, Australia", "IPAddress" : "202.51.170.6" }, { "ServerID" : 40, "CheckPointID" : 4, "CheckPointName" : "Tampa, FL, USA", "IPAddress" : "66.230.202.37" } ]

Obtenir le statut actuel d’un moniteur

Les Operations suivantes renvoient un ou plusieurs moniteurs avec leur statut actuel.

Operation Method URL Return value
List status of all monitors in group GET /probegroups/{ProbeGroupGuid}/status List<Status>
Status of a single monitor GET /probes/{ProbeGuid}/status Status

Champ défini : Status

Field name Type Comments
ProbeGuid Guid Unique ID for the monitor.
ErrorLevel Enumeration Values: NoError, Unconfirmed, Confirmed
ErrorDescription String Description of the current error for this monitor, or “OK” if there is no error.
LastCheck DateTime The timestamp of the last check that was performed for this monitor.
CheckPointID Integer The ID of the checkpoint server that performed the last check.
Uptime Float Uptime for this monitor, for the last 24 hours.

Exemple

Pour récupérer le statut d’un groupe de moniteurs, envoyez une requête GET à /probegroups/{probegroupguid}/status. Le corps de la réponse contient une liste d’objets de statut.

[ { "ProbeGuid" : "2a1d74876f8247139c731e9b4dce203b", "ErrorLevel" : "NoError", "LastCheck" : "2015-06-07T08:56:18", "CheckPointID" : 36 }, { "ProbeGuid" : "fa15240ae9474cff8f3e6488678627fe", "ErrorLevel" : "Confirmed", "LastCheck" : "2015-06-07T08:58:18", "CheckPointID" : 33 }, { "ProbeGuid" : "b142467ed373f5c18f0d68d16850952f", "ErrorLevel" : "NoError", "LastCheck" : "2015-06-07T08:59:45", "CheckPointID" : 55 }, { "ProbeGuid" : "ed2a88cd280b404aab9a9167ddc5ddb0", "ErrorLevel" : "NoError", "LastCheck" : "2015-06-07T08:56:18", "CheckPointID" : 18 } ]

Obtenir des statistiques pour moniteurs et groupes de moniteurs

L’opération suivante renvoie des données statistiques (sur la disponibilité, les temps de chargement, etc. - voir ci-dessous) pour les moniteurs demandés, sur la période de temps spécifiée.

OperationMethodURLReturn value
List statistical data for a groupGET/probegroups/{ProbeGroupGuid}/statistics? Start=<startdate>&End=<enddate>&Dimension=<dimension>
Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result.
Dimension: how to group/aggregate the results. Possible values: Day, Week, Month, Year, ProbeGroup, Probe, Checkpoint, ErrorCode, ErrorLevel
List<Statistics>
List statistical data for a monitorGET/probes/{ProbeGuid}/statistics? Start=<startdate>&End=<enddate>&Dimension=<dimension>
Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result.
Dimension: how to group/aggregate the results. Possible values: Day, Week, Month, Year, ProbeGroup, Probe, Checkpoint, ErrorCode, ErrorLevel
List<Statistics>

Champ défini : Statistics

Field name Type Comments
ProbeGuid Guid Unique ID for the monitor.
ErrorLevel Enumeration Values: NoError, Unconfirmed, Confirmed
LastCheck DateTime The timestamp of the last check that was performed for this monitor.
CheckPointID Integer The ID of the checkpoint server that performed the last check.
Dimension String A value describing the dimension, according to the specified dimension in the request. Example: when a dimension ‘Month’ was specified, this field could contain “2015/01”, “2015/02”, etc. If a dimension ‘Probe’ was specified, this could contain the monitor name, etc.
SLAPercentage Float The SLA target uptime percentage
SLATotalTime Float The SLA target total load time (in seconds)
SLAOperatorResponseTime Float The SLA target operator response time (in minutes)
AvgOperatorResponseTime Float The average operator response time (in minutes)
PercentageOK Float The percentage of OK-time
PercentageError Float The percentage of Error-time
PercentageUnknown Float The percentage of time that the monitored site’s status is unknown due to pausing the monitor or while the monitor is disabled in a maintenance window.
PercentageUptime Float The percentage of Uptime
TotalChecks Integer The total number of checks
Errors Integer The total number of confirmed errors
UnconfirmedErrors Integer The total number of unconfirmed errors
Alerts Integer The number of alerts
SecondsOK Integer The total number of OK-time in seconds
SecondsError Integer The total number of Error-time in seconds
SecondsUnknown Integer The total time in seconds that the monitored site’s status is unknown due to pausing the monitor or while the monitor is disabled in a maintenance window.
AverageTotalTime Float The average total load time
AverageResolveTime Float The average resolve time
AverageConnectionTime Float The average connection time
AverageDownloadTime Float The average download time
AverageTotalBytes Float The average total number of bytes downloaded

Exemple

Pour obtenir le statut d’un groupe de moniteurs, pour la période de Janvier à Mars 2015, regroupé par mois, envoyez une requête GET à /probegroups/{probegroupguid}/statistiques?Start=2015/01/01&End=2015/04/01&Dimension=Month.

Le corps de la réponse contient une liste d’objets statistiques.

[ { "Dimension" : "2015/1", "Alerts" : 0, "SLAPercentage" : 99, "SLATotalTime" : 2, "SLAOperatorResponseTime" : 15, "AvgOperatorResponseTime" : 0, "PercentageOK" : 95.10564, "PercentageError" : 0.200337, "PercentageUnknown" : 4.694026, "PercentageUptime" : 99.79966, "TotalChecks" : 786998, "Errors" : 1473, "UnconfirmedErrors" : 36925, "SecondsOK" : 224419742, "SecondsError" : 472733, "SecondsUnknown" : 11076442, "AverageTotalTime" : 1.685304, "AverageResolveTime" : 0.004690104, "AverageConnectionTime" : 0.176703, "AverageDownloadTime" : 1.503535, "AverageTotalBytes" : 13259 }, ... ]

Obtenir l’historique des alertes

L’opération suivante renvoie une liste des alertes qui ont été générées pour les moniteurs dans le groupe de moniteurs spécifié, pendant la période de temps spécifiée.

OperationMethodURLReturn value
List alert history for all monitors in groupGET/probegroups/{ProbeGroupGuid}/alerts? Start=<startdate>&End=<enddate>
Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result.
List<Alert>

Champ défini : Alert

Field name Type Comments
ProbeGuid Guid ID that identifies the monitor for this alert
Timestamp DateTime The date and time for this alert
FirstError DateTime The date and time of the first error that triggered this alert
AlertType Enumeration Value that indicates if this is an error-alert or an OK-alert. Values: error, ok
ErrorDescription String Generic name of the type of error that occurred
ErrorDetails String When available, contains more detailed information about the error that caused this alert. For HTTP(S) monitors, this contains the description of the HTTP error. For transactions, it includes the step number and name of the step which triggered the error.

Exemple

Pour récupérer l’historique des alertes pour un groupe de moniteurs, pour le 31 mai 2015, envoyez une demande GET à /probegroups/{probegroupguid}/alerts?Start=2015/05/31&End=2015/06/01

Le corps de la réponse contient une liste d’objets d’alerte.

[ { "ProbeGuid" : "a3136b5df13740e793d428480522be7b", "Timestamp" : "2015-05-31T16:47:25", "FirstError" : "2015-05-31T16:37:50", "AlertType" : "ok" }, { "ProbeGuid" : "a3136b5df13740e793d428480522be7b", "Timestamp" : "2015-05-31T16:42:54", "FirstError" : "2015-05-31T16:37:50", "AlertType" : "error" }, { "ProbeGuid" : "a3136b5df13740e793d428480522be7b", "Timestamp" : "2015-05-31T12:41:26", "FirstError" : "2015-05-31T12:24:46", "AlertType" : "ok" } ]

En utilisant ce site, vous consentez à l’utilisation de cookies conformément à notre Politique de cookies.