Die Uptrends API ermöglicht Ihnen, Informationen zu Prüfobjekten oder Prüfobjektgruppen direkt in Ihrem Uptrends Account zu ändern. Die API ist ein Webservice, die eine REST-Schnittstelle nutzt, um grundlegende CRUD-Operationen (Create, Read, Update, Delete) bei Uptrends-Einheiten auszuführen.
Sie können auch Daten von Ihrem Account abrufen. Dies schließt den aktuellen Status Ihres Prüfobjekts, Statistiken zur Performance Ihrer Prüfobjekte und Prüfobjektgruppen sowie die Meldehistorie Ihrer Prüfobjekte ein.
Voraussetzungen
Zur Nutzung der Uptrends API benötigen Sie Folgendes:
- Den Benutzernamen und das Passwort eines Uptrends Accounts oder die Anmeldeinformationen eines Operators in diesem Account
- 2. Zugang zur API-Domain unter: https://api.uptrends.com/v3
Zugriff auf die API
Die API kann anhand des spezifizierten Basis-URL mithilfe des HTTPS-Protokolls aufgerufen werden.
Authentifizierung
Die API erfordert eine HTTP Basis-Authentifizierung, um auf die Information zuzugreifen. Sie benötigen Anmeldedaten von Uptrends, um Zugriff zu erhalten.
Der von Ihnen verwendete Benutzername kann Ihr Hauptanmeldename für Ihren Uptrends Account sein oder ein Operator, den Sie im Account eingerichtet haben. Bitte beachten Sie, dass Sie einen Administrator-Account (d. h. ein Operator, der Mitglied der Administratorgruppe) benötigen, wenn Sie Aktualisierungen vornehmen wollen.
HTTP-Methoden
Auf Grundlage der HTTP-Methode werden die folgenden Aktionen unterstützt:
| 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) |
Fehlerhandhabung
Wenn ein Fehler auftritt, wird ein HTTP-Fehlercode 400 (Bad Request) mit einer Fehlerbeschreibung im Antwortinhalt zurückgegeben.
Die API unterstützt den Transfer von Daten in den folgenden Formaten:
| Data format | Http Content-type | Override URL parameter |
|---|---|---|
| XML | application/xml | ?format=xml |
| JSON | application/json | ?format=json To embed the response in a jsonp callback append ?callback=myCallback |
| JSV | text/jsv | ?format=jsv |
| CSV | text/csv | ?format=csv |
| SOAP 1.1 | application/xml | ?format=soap11 |
| SOAP 1.2 | application/xml | ?format=soap12 |
Format
Einige API-Operationen geben DateTime-Daten zurück. Das Format der Daten wird gemäß dem Standard ISO 8601 sein, aber ohne Zeitzoneninformation. Die Daten werden in Ortszeit ausgedrückt in Bezug auf die Zeitzone, die im Uptrends Account eingestellt ist.
Beispiel:
Ein Datum und eine Uhrzeit wie 1. Juni 2015 21:35:59 werden angezeigt als:
2015-06-01T21:35:59
unabhängig von der Zeitzone in Ihren Account-Einstellungen. Wenn Ihre Zeitzone EST (UTC -05:00) lautet, sollte dieser Wert als 1. Juni 2015 09:35:50 PM, EST, interpretiert werden.
API-Operationen
Alle Operationen, die auf dem folgenden Basis-URL ausgeführt werden:
Basis-URL: https://api.uptrends.com/v3/<operation url>
- Beispiel 1: Der folgende URL liefert eine Liste aller Prüfobjektgruppen in Ihrem Account:
https://api.uptrends.com/v3/probegroups - Beispiel 2: Um den Namen einer Prüfobjektgruppe zu aktualisieren, führen Sie einen HTTP PUT zum folgenden URL:
https://api.uptrends.com/v3/probegroups/688b2eab-f650-45e6-80f2-0158273d8257
Der Anfragetext sollte JSON- oder XML-Daten mit folgendem Inhalt enthalten:
{"Name":"Updated ProbeGroupName"}
Für Aktualisierungen müssen Sie nur die Felder angeben, die Sie ändern möchten. Felder, die bei der Anfrage ausgelassen werden, bleiben unverändert.
Monitor operations
| Operation | Method | URL | Return value |
|---|---|---|---|
| List all monitors | GET | /probes | List<Probe> |
| Create monitor | POST | /probes | Probe |
| Get monitor | GET | /probes/{ProbeGuid} | Probe |
| Update monitor | PUT | /probes/{ProbeGuid} | (empty) |
| Delete monitor | DELETE | /probes/{ProbeGuid} | (empty) |
Field definition: Probe
| Field name | Type | Comments |
|---|---|---|
| Guid | Guid | Unique monitor ID |
| Name | String | Name of the monitor |
| URL | String | URL or IP address of the website, (web/database/mail/FTP/DNS-) server to check. |
| Port | Integer | Port number |
| CheckFrequency | Integer | Time 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. |
| ProbeType | Enumeration | Allowed values: Http, Https, Connect, Ping, POP3, SMTP, IMAP, FTP, MySQL, MSSQL, WebserviceHttp, WebserviceHttps, DNS, FullPageCheck, RealBrowserCheck Note: the monitor type Transaction is not supported. |
| IsActive | Boolean | Indicates whether the monitor is active. Inactive monitors are not measured. Allowed values: True, False |
| GenerateAlert | Boolean | Indicates whether to send alerts for this monitor. Allowed values: True, False |
| Notes | String | User-defined notes. This value is only displayed in the Uptrends application. |
| PerformanceLimit1 | Integer | First load time limit in milliseconds. |
| PerformanceLimit2 | Integer | Second load time limit in milliseconds. |
| ErrorOnLimit1 | Boolean | Indicates whether to generate errors when PerformanceLimit1 is exceeded. Allowed values: True, False |
| ErrorOnLimit2 | Boolean | Indicates whether to generate errors when PerformanceLimit2 is exceeded. Allowed values: True, False |
| MinBytes | Integer | The minimum number of bytes in the server response to check for. |
| ErrorOnMinBytes | Boolean | Indicates whether to generate errors when MinBytes is exceeded. Allowed values: True, False |
| Timeout | Integer | The time limit for the complete test, in milliseconds. |
| TcpConnectTimeout | Integer | The time limit for the initial TCP connection, in milliseconds. |
| MatchPattern | String | Content to check for in the response of HTTP requests. Regular expressions are allowed. |
| DnsLookupMode | Enumeration | How 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). |
| UserAgent | String | The user agent (browser identification value) to specify for HTTP(S), Real Browser Check and Full Page Check monitors. |
| UserName | String | The username to specify as Basic/Digest/NTLM Authentication (when available), or the login name for FTP, FTPS or SQL monitors. |
| Password | String | The 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. |
| IsCompetitor | Boolean | Indicates whether this monitor should be included in the competitor analysis report. Allowed values: True, False |
| Checkpoints | String | An 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. |
| Specific values for DNS monitors: | ||
| DNSQueryType | Enumeration | The type of DNS query. Allowed values: ARecord, CNAMERecord, MXRecord, NSRecord, TXTRecord |
| DNSTestValue | String | The value to query for a DNS monitor. For example, when checking an A record, this value contains the domain name to check. |
| DNSExpectedResult | String | The expected result of the DNS query. Regular expressions are allowed. |
| Specific values for Database monitors: | ||
| DatabaseName | String | |
| Specific values for HTTP(S) and WebserviceHTTP(S) monitors: | ||
| HttpMethod | Enumeration | Allowed values: Get, Post |
| PostData | String | Content for the request body in case of a Post request. |
| Specific values for Connect monitors: | ||
| ConnectMethod | Enumeration | Allowed values: Tcp, Udp |
Prüfobjektoperationen
Um ein DNS-Prüfobjekt zum Account hinzuzufügen, senden Sie eine POST-Anfrage an https://api.uptrends.com/v3/probes, stellen Sie die notwendige Basis-Authentifizierung bereit, setzen Sie den Content-Type und Accept-Header auf application/json und geben Sie den folgenden Inhalt als Anfragetext:
{ "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" }
Operationen bei Prüfobjektgruppen
| 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) |
Felddefinition: Prüfobjektgruppe
| Field name | Type | Comments |
|---|---|---|
| Guid | Guid | Unique monitor group ID |
| Name | String | Name of the monitor group |
Beispiel 1
Um eine Liste aller Prüfobjektgruppen zu erhalten, führen Sie eine GET-Anfrage an /probegroups aus. Der Antworttext enthält eine Liste der Prüfobjektgruppen:
[ { "Guid" : "680a5071c6d645a3b56945053b2d6a90", "Name" : "All probes" }, { "Guid" : "b1d9f5451aa04600992dc02d36f80e40", "Name" : "Probe group 1" }, { "Guid" : "25532138344a407597ad679ba1176aae", "Name" : "My other probe group" }, { "Guid" : "939110bb5d514dfe95e553b8a7dc8cde", "Name" : "Test probe group" } ]
Beispiel 2
Um eine neue Gruppe zu erstellen, führen Sie eine POST-Anfrage an /probegroups aus. Der Anfragetext sollte den Namen der neuen Gruppe spezifizieren:
{"Name":"My new group"}
Der Antworttext wird diese neue Gruppe enthalten:
{"Guid":"bd6e2c7e8a2348dc88206460d73f3658","Name":" My new group "}
Operationen bei Prüfobjektgruppenmitgliedern
Die folgenden Methoden funktionieren bei Prüfobjektgruppenmitgliedern, d. h. welche Prüfobjekte Teil welcher Gruppen sind.
| 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) |
Beispiel 1
Um alle Prüfobjekte in einer Prüfobjektgruppe zu erhalten, senden Sie eine GET-Anfrage an /probegroups/{ProbeGroupGuid}/members. Der Antworttext wird eine Liste der Prüfobjekte enthalten. (Daten in diesem Beispiel sind gekürzt):
[ { "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, } ]
Beispiel 2
Um ein Prüfobjekt zu einer Gruppe hinzuzufügen, senden Sie eine POST-Anfrage an /probegroups/{ProbeGroupGuid}/members. Der Anfragetext sollte eine Referenz zum Prüfobjekt Guid, das zur Gruppe hinzugefügt wird, enthalten:
{ "ProbeGuid" : "c4c8f5df7d02410bb1a837ce24bb2e8b" }
Checkpoint-Server auflisten
Die folgende Operation gibt eine Liste der Checkpoint-Server von Uptrends aus. Diese Information kann für zwei Dinge genutzt werden:
- Die CheckpointID-Werte sollten bei der Spezifizierung bestimmter Checkpoints für ein Prüfobjekt genutzt werden.
- Die Liste enthält die IP-Adressen für einen Checkpoint-Server. Bitte beachten Sie, dass ein Checkpoint über mehrere Checkpoint-Server verfügen und daher mehrere IP-Adressen aufweisen kann.
| Operation | Method | URL | Return value |
|---|---|---|---|
| List all checkpoint servers | GET | /checkpointservers | List<CheckpointServer> |
Felddefinition: 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. |
Beispiel
Um die Liste der Checkpoint-Server abzurufen, senden Sie eine GET-Anfrage an /checkpointservers. Der Antworttext enthält eine Liste der Checkpoints (Daten in diesem Beispiel sind verkürzt). Bitte beachten Sie, dass der London-Checkpoint in diesem Beispiel (CheckpointID = 1) zwei IP-Adressen aufweist.
[ { "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" } ]
Aktuellen Prüfobjektstatus abrufen
Die folgenden Operationen geben eine oder mehr Prüfobjekte und ihren aktuellen Monitoringstatus aus.
| 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 |
Felddefinition: 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. |
Beispiel
Um den Status für eine Gruppe Prüfobjekte abzurufen, senden Sie eine GET-Anfrage an /probegroups/{probegroupguid}/status. Der Antworttext enthält eine Liste von Statusobjekten.
[ { "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 } ]
Statistiken für eine Prüfobjektgruppe und Prüfobjekte abrufen
Die folgende Operation gibt statistische Daten (einschließlich Verfügbarkeit, Ladezeiten usw., siehe unten) für die angefragten Prüfobjekte für einen spezifizierten Zeitraum aus.
| Operation | Method | URL | Return value |
|---|---|---|---|
| List statistical data for a group | GET | /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 monitor | GET | /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> |
Felddefinition: Statistiken
| 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 |
Beispiel
Um den Status für eine Prüfobjektgruppe für Januar, Februar und März 2015, gruppiert nach Monat abzurufen, senden Sie eine GET-Anfrage an /probegroups/{probegroupguid}/statistics?Start=2015/01/01&End=2015/04/01&Dimension=Month.
Der Antworttext enthält eine Liste der Statistikobjekte.
[ { "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 }, ... ]
Meldehistorie abrufen
Die folgende Operation gibt eine Liste der Alarmierungen aus, die für die Prüfobjekte in der spezifizierten Prüfobjektgruppe während des angegebenen Zeitraums erzeugt wurden.
| Operation | Method | URL | Return value |
|---|---|---|---|
| List alert history for all monitors in group | GET | /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> |
Felddefinition: Alarm
| 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. |
Beispiel
Um die Meldehistorie für eine Gruppe von Prüfobjekten für den 31. Mai 2015 zu erhalten, senden Sie eine GET-Anfrage an /probegroups/{probegroupguid}/alerts?Start=2015/05/31&End=2015/06/01
Der Antworttext enthält eine Liste der Statistikobjekte.
[ { "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" } ]