Przykłady wywołań operacji API

Ten dokument zawiera przykłady wywołań operacji API wraz z przykładowymi odpowiedziami. We wszystkich przykładach należy zastąpić USERNAME i PASSWORD własnym loginem i hasłem.

Konto

Pobranie danych konta

Informacje o własnym koncie można pobrać w następujący sposób:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/accounts/my_account'
{
   "id" : 100,
   "is_activated" : true,
   "is_blocked" : false,
   "is_read_only" : false,
   "language_id" : "pl",
   "name" : "Example Account",
   "package_id" : 438,
   "parent_account_id" : null,
   "time_zone_id" : "europe_warsaw",
   "username" : "USERNAME"
}

Pobranie danych użytkownika

Dane właściciela konta:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/user_data/my_user_data'
{
   "address" : null,
   "contact_person" : "John Smith",
   "email_address" : "john.smith@monit24.pl",
   "id" : 100,
   "phone_number" : "111111111",
   "settings" : [],
   "tax_identification_number" : null
}

Pobranie limitów własnego konta

Limity usług, stacji monitorujących, kanałów powiadomień itp. są zdefiniowane w pakiecie przypisanym do konta. Każde konto ma przypisany dokładnie jeden pakiet. Pakiet własnego konta można pobrać w nastąpujący sposób:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/packages/my_package'
{
   "available_notification_channel_ids" : [
      "email",
      "email_dedicated",
      "email_extended",
      "email_short",
      "gadu_gadu",
      "jabber",
      "sms"
   ],
   "available_service_types" : [
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "dns"
      },
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "fullpage"
      },
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "fullpagehttps"
      },
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "http"
      },
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "https"
      },
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "ping"
      },
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "smtp_helo"
      },
      {
         "maximum_services" : null,
         "minimum_interval" : null,
         "service_type_id" : "tcp_connect"
      }
   ],
   "id" : 438,
   "is_available_for_new_accounts" : true,
   "maximum_sensors" : 5,
   "maximum_services" : 10,
   "maximum_sms_numbers" : null,
   "minimum_interval" : 120,
   "monthly_reports_limit" : null,
   "name" : "ZAAWANSOWANY"
}

Usługi

Pobranie listy usług

Pobranie listy (uproszczonych) obiektów usług, do których użytkownik ma dostęp:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services?fields=id,name,address,interval,type_id,is_active'
[
   {
      "address" : "monit24.pl",
      "id" : 1,
      "interval" : 900,
      "is_active" : false,
      "name" : "Usługa testowa 1",
      "type_id" : "http"
   },
   {
      "address" : "api.monit24.pl",
      "id" : 2,
      "interval" : 600,
      "is_active" : false,
      "name" : "Usługa testowa 2",
      "type_id" : "https"
   }
]

Uwaga: domyślnie lista ta zawiera jedynie pierwszych 10 znalezionych usług, ze względu na paginację. Szczegóły zasad działania operacji zwracających listę obiektów są opisane w tym dokumencie.

Pobranie listy własnych usług

Aby pobrać tylko własne usługi (bez udostępnionych przez innych użytkowników), można użyć zapytania:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/accounts/my_account/services'

Pobranie listy usług, które możemy modyfikować

Usługi, które można modyfikować (własne lub udostępnione) można pobrać filtrując po permissions.update:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services?permissions.update=true'

Pobranie listy usług w wybranej grupie

Usługi należące do wybranej grupy można pobrać na dwa sposoby: flitrując po group_id...

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services?group_id=5000'

...lub używając zasobu /groups/{_id}/services:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/groups/5000/services'

Pobranie stacji monitorujących, z których usługa jest monitorowana

Stacje monitorujące, z których odbywa się monitoring usługi (nie licząc wylosowanych stacji zastępczych) można pobrać następująco:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/1/monitoring_sensors?fields=id,name,city'
[
   {
      "city" : "Warszawa",
      "id" : 2,
      "name" : "Warszawa01 217.17.42.71"
   },
   {
      "city" : "Poznań",
      "id" : 18,
      "name" : "Poznan01 91.228.197.228"
   }
]

Obecnie lista ta jest tożsama z listą stacji monitorujących przypisanych do grupy, do której należy usługa.

Utworzenie usługi

Utworzenie nowej usługi typu http, monitorującej adres monit24.pl metodą GET co 1 godzinę i należącej do grupy 5000:

curl -u USERNAME:PASSWORD -X POST -H 'Content-Type: application/json' \
   -d '{
      "type_id" : "http",
      "address" : "monit24.pl",
      "interval" : 3600,
      "group_id" : 5000,
      "name" : "Usługa testowa",
      "extended_settings" : {
          "http_method" : "GET"
      }
   }' 'https://api.monit24.pl/v3/services'
{
   "id" : 16
}

Pole extended_settings zawiera szczegółowe ustawienia usługi. Lista dostępnych ustawień szczegółowych zależy od typu usługi; dla danego typu można ją pobrać za pomocą wywołania GET /service_types/{id_typu}/extended_setting_formats.

Zatrzymanie monitoringu usługi

Monitoring usługi można włączyć lub wyłączyć modyfikując jej atrybut is_active:

curl -u USERNAME:PASSWORD -X PUT -H 'Content-Type: application/json' \
   -d '{
      "is_active" : false
   }' 'https://api.monit24.pl/v3/services/16'

Usunięcie usługi

Usunięcie usługi za pomocą metody HTTP DELETE:

curl -u USERNAME:PASSWORD -X DELETE 'https://api.monit24.pl/v3/services/16'

Wymuszenie analizy działania usługi

Jeśli limity minutowe, godzinne i dobowe wymuszeń analizy działania usługi nie zostały przekroczone, można zlecić analizę (sprawdzenie) działania usługi poza przewidzianym harmonogramem:

curl -u USERNAME:PASSWORD -X POST 'https://api.monit24.pl/v3/services/16/force_analysis'

Funkcja ta przydaje się np. kiedy zmieniono ustawienia usługi i zachodzi potrzeba upewnienia się, że będzie działała zgodnie z oczekiwaniami.

Informacje o statusie usługi

Aktualny status monitoringu, działania i powiadomień dla usługi można pobrać za pomocą zasobu service_statuses. Każda usługa ma dokładnie jeden obiekt statusu, o takim samym identyfikatorze jak usługa.

Pobranie statusu dla usługi o identyfikatorze 16:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/service_statuses/16'
{
   "check_status" : "ok",
   "check_status_is_up_to_date" : false,
   "id" : 1,
   "last_analysis_id" : "148442671420234",
   "last_analysis_time" : "2017-01-14T20:45:16Z",
   "last_check_status_change_time" : "2017-01-14T20:00:18Z",
   "last_failure_analysis_id" : "147190414120128",
   "last_failure_analysis_time" : "2016-08-22T22:15:46Z",
   "last_ok_analysis_id" : "148442671420234",
   "last_ok_analysis_time" : "2017-01-14T20:45:16Z",
   "monitoring_status" : "off",
   "notifications_status" : "on",
   "summary" : "paused"
}

Grupy

Pobranie listy grup

Lista grup, do których użytkownik ma dostęp:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/groups'
[
   {
      "id" : 200,
      "is_default" : true,
      "periodic_daily_reports" : true,
      "periodic_monthly_reports" : true,
      "periodic_weekly_reports" : true,
      "name" : "Grupa domyślna",
      "owner_id" : 100,
      "sensor_ids" : [
         2,
         18
      ]
   },
   {
      "id" : 4,
      "is_default" : false,
      "periodic_daily_reports" : false,
      "periodic_monthly_reports" : false,
      "periodic_weekly_reports" : false,
      "name" : "test",
      "owner_id" : 100,
      "sensor_ids" : [
         2,
         30,
         34
      ]
   }
]

Pobranie grupy domyślnej własnego konta

Każde z kont posiada dokładnie jedną grupę domyślną (nowe usługi są do niej dodawane jeśli przy tworzeniu nie zostanie podana inna grupa). Własną grupę domyślną można pobrać w następujący sposób:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/groups/my_default_group'
{
   "id" : 200,
   "is_default" : true,
   "periodic_daily_reports" : true,
   "periodic_monthly_reports" : true,
   "periodic_weekly_reports" : true,
   "name" : "Grupa domyślna",
   "owner_id" : 100,
   "sensor_ids" : [
      2,
      18
   ]
}

Pobranie listy własnych grup

Pobranie listy własnych grup (bez udostępnionych przez innych użytkowników):

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/accounts/my_account/groups'

Utworzenie grupy

Utworzenie grupy z określeniem stacji monitorujących i wyłączonymi raportami dobowymi:

curl -u USERNAME:PASSWORD -X POST -H 'Content-Type: application/json' \
   -d '{
      "name" : "Nowa grupa",
      "periodic_daily_reports" : false,
      "sensor_ids" : [8, 10, 22]
   }' 'https://api.monit24.pl/v3/groups'
{
   "id" : 150
}

Zmiana stacji monitorujących przypisanych do grupy

Stacje monitorujące przypisane do grupy można zmienić poprzez modyfikację jej atrybutu sensor_ids:

curl -u USERNAME:PASSWORD -X PUT -H 'Content-Type: application/json' \
   -d '{
      "sensor_ids" : [16, 17, 36]
   }' 'https://api.monit24.pl/v3/groups/150'

Usunięcie grupy

Usunięcie grupy razem ze wszystkimi usługami, adresami powiadomień i raportów:

curl -u USERNAME:PASSWORD -X DELETE 'https://api.monit24.pl/v3/groups/150'

Typy usług

Lista typów usług

Lista typów usług, do których użytkownik ma dostęp:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/service_types?fields=id,name,address_prefix'
[
   {
      "address_prefix" : "dns://",
      "id" : "dns",
      "name" : "DNS"
   },
   {
      "address_prefix" : "http://",
      "id" : "fullpage",
      "name" : "FullPage"
   },
   {
      "address_prefix" : "https://",
      "id" : "fullpagehttps",
      "name" : "FullPageHttps"
   },
   {
      "address_prefix" : "http://",
      "id" : "http",
      "name" : "http"
   },
   {
      "address_prefix" : "https://",
      "id" : "https",
      "name" : "https"
   },
   {
      "address_prefix" : "ping://",
      "id" : "ping",
      "name" : "ping"
   },
   {
      "address_prefix" : "smtp://",
      "id" : "smtp_helo",
      "name" : "smtp-helo"
   },
   {
      "address_prefix" : "host://",
      "id" : "tcp_connect",
      "name" : "TCP Connect"
   }
]

Lista typów usług, które możemy utworzyć w grupie

W zależności od limitów konta, na którym usługa jest tworzona, mogą być dostępne różne typy usług. Ich listę dla wybranej grupy można pobrać następująco:

curl -u USERNAME:PASSWORD \
   'https://api.monit24.pl/v3/groups/100/available_service_types?\
   fields=?fields=minimum_interval,remaining_services,service_type_id'
[
   {
      "minimum_interval" : 120,
      "remaining_services" : 2,
      "service_type_id" : "dns"
   },
   {
      "minimum_interval" : 240,
      "remaining_services" : 2,
      "service_type_id" : "fullpage"
   },
   {
      "minimum_interval" : 300,
      "remaining_services" : 0,
      "service_type_id" : "fullpagehttps"
   },
   {
      "minimum_interval" : 60,
      "remaining_services" : 2,
      "service_type_id" : "http"
   },
   {
      "minimum_interval" : 120,
      "remaining_services" : 1,
      "service_type_id" : "https"
   },
   {
      "minimum_interval" : 120,
      "remaining_services" : 2,
      "service_type_id" : "ping"
   },
   {
      "minimum_interval" : 120,
      "remaining_services" : 2,
      "service_type_id" : "smtp_helo"
   },
   {
      "minimum_interval" : 180,
      "remaining_services" : 2,
      "service_type_id" : "tcp_connect"
   }
]

Pole remaining_services oznacza liczbę usług danego typu, które jeszcze można utworzyć w wybranej grupie. 0 oznacza, że typ usługi jest dostępny w pakiecie, ale wszystkie usługi tego typu zostały już wykorzystane. Pole minimum_interval oznacza minimalny odstęp pomiędzy sprawdzeniami dostępny dla usług danego typu.

Pobranie zaawansowanych ustawień usług danego typu

Każdy typ usługi ma określoną listę zaawanowanych ustawień (`extended_settings`) dostępnych dla usług tego typu. Dla danego typu można pobrać listę specyfikacji dostępnych ustawień za pomocą wywołania `GET /service_types/{id_typu}/extended_setting_formats`. Przykład dla typu http:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/service_types/ping/extended_setting_formats'
[  
   {  
      "default" : 64,
      "description" : "Rozmiar pakietu danych",
      "enum" : null,
      "is_nullable" : false,
      "maximum" : 65535,
      "maximum_length" : null,
      "minimum" : 1,
      "minimum_length" : null,
      "pattern" : null,
      "service_type_id" : "ping",
      "setting_id" : "bytes_to_send",
      "suggested_form_element" : "text",
      "type" : "integer"
   },
   {  
      "default" : 3000,
      "description" : "Czas oczekiwania na odpowiedź",
      "enum" : null,
      "is_nullable" : false,
      "maximum" : 120000,
      "maximum_length" : null,
      "minimum" : 1,
      "minimum_length" : null,
      "pattern" : null,
      "service_type_id" : "ping",
      "setting_id" : "reply_timeout",
      "suggested_form_element" : "text",
      "type" : "integer"
   },
   {  
      "default" : 51,
      "description" : "Ile procent stacji monitorujących musi zgłosić błąd, aby został on uznany",
      "enum" : null,
      "is_nullable" : false,
      "maximum" : 100,
      "maximum_length" : null,
      "minimum" : 1,
      "minimum_length" : null,
      "pattern" : null,
      "service_type_id" : "ping",
      "setting_id" : "error_tolerance",
      "suggested_form_element" : "percent",
      "type" : "integer"
   },
   {  
      "default" : true,
      "description" : "Losuj zastępcze stacje monitorujące w przypadku awarii stacji",
      "enum" : null,
      "is_nullable" : false,
      "maximum" : null,
      "maximum_length" : null,
      "minimum" : null,
      "minimum_length" : null,
      "pattern" : null,
      "service_type_id" : "ping",
      "setting_id" : "sensors_failover",
      "suggested_form_element" : "checkbox",
      "type" : "boolean"
   }
]

Historia monitoringu

Lista analiz działania usługi

Pobranie listy analiz działania usługi z ostatniej doby:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/111/history/analyses'
[
   {
      "analysis_id" : "148555590120222",
      "error_checks_count" : 2,
      "error_tolerance" : 51,
      "failure" : true,
      "ok_checks_count" : 0,
      "service_id" : 111,
      "time" : "2017-01-27T22:25:06Z",
      "unknown_checks_count" : 0
   },
   {
      "analysis_id" : "148555578420416",
      "error_checks_count" : 0,
      "error_tolerance" : 51,
      "failure" : false,
      "ok_checks_count" : 2,
      "service_id" : 111,
      "time" : "2017-01-27T22:23:06Z",
      "unknown_checks_count" : 0
   },
   {
      "analysis_id" : "148555575220134",
      "error_checks_count" : 0,
      "error_tolerance" : 51,
      "failure" : false,
      "ok_checks_count" : 2,
      "service_id" : 111,
      "time" : "2017-01-27T22:22:34Z",
      "unknown_checks_count" : 0
   }
]

Uwaga: poza ograniczonym przedziałem czasowym (maksymalnie 40 dni) lista ta obsługuje standardowe mechanizmy paginacji. Przedział czasowy można wybrać za pomocą parametrów GET from i to, domyślnie używana jest ostatnia doba.

Lista sprawdzeń w analizie

Lista sprawdzeń na poszczególnych stacjach wchodzących w skład wybranej analizy:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/111/history/analyses/148555590120222/checks'
[
   {
      "analysis_id" : "148555590120222",
      "data_size" : 16384,
      "error_type_id" : 1000001,
      "error_message" : "Kod strony nie zawiera wymaganego wyrazenia: invalid_regex",
      "har_available" : false,
      "path_step" : null,
      "response_time" : 200,
      "result" : "error",
      "sensor_id" : 1,
      "service_id" : 111,
      "time" : "2017-01-27T22:25:06Z"
   },
   {
      "analysis_id" : "148555590120222",
      "data_size" : 0,
      "error_type_id" : 1000001,
      "error_message" : "Kod strony nie zawiera wymaganego wyrazenia: invalid_regex",
      "har_available" : false,
      "path_step" : null,
      "response_time" : 244,
      "result" : "error",
      "sensor_id" : 2,
      "service_id" : 111,
      "time" : "2017-01-27T22:25:06Z"
   }
]

Szczegóły sprawdzenia

Szczegóły wybranego sprawdzenia (z analizy jak w przykładzie wyżej, dla stacji monitorującej 2):

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/111/history/analyses/148555590120222/checks/2/details'
{
   "analysis_id" : "148555590120222",
   "base_url" : "http://monit24.pl",
   "content_available" : true,
   "content_type" : "text/html",
   "file_name" : "/",
   "response_headers" : "Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0\n(...)",
   "sensor_id" : 2,
   "service_id" : 111,
   "step_data" : null
}

Treść monitorowanej strony z momentu awarii

Jeśli w szczegółach sprawdzenia content_available ma wartość true, to możliwe jest pobranie zawartości strony z momentu awarii:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/111/history/analyses/148555590120222/checks/2/artifacts/content/plain'

Pliki HAR

W podobny sposób można pobrać plik HAR dla sprawdzenia (jeśli atrybut har_available sprawdzenia ma wartość true):

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/111/history/analyses/148555590120222/checks/2/artifacts/har/plain'

Dziennik awarii

Wpisy w dzienniku zmian stanów usługi można pobrać w następujący sposób:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/111/history/status_changes'
[
   {
      "change_id" : "148555575220134",
      "description" : "Poprawne działanie",
      "duration" : 153,
      "end_time" : "2017-01-27T22:25:07Z",
      "first_analysis_id" : "148555575220134",
      "pause_reason" : null,
      "service_id" : 111,
      "start_time" : "2017-01-27T22:22:34Z",
      "status" : "ok"
   },
   {
      "change_id" : "148555590120222",
      "description" : "Awaria (Reply does not match to requested pattern)",
      "duration" : 652,
      "end_time" : null,
      "first_analysis_id" : "148555590120222",
      "pause_reason" : null,
      "service_id" : 111,
      "start_time" : "2017-01-27T22:25:06Z",
      "status" : "failure"
   }
]

Domyślnie zwracana jest cała historia zmian stanów usługi, ze standardową paginacją.

Ostatnia awaria usługi

Ostatnią awarię (przejście w stan failure) usługi można pobrać następującym zapytaniem:

curl -u USERNAME:PASSWORD \
   'https://api.monit24.pl/v3/services/111/history/status_changes?status=failure&sort=-start_time&limit=1'
[
   {
      "change_id" : "148555590120222",
      "description" : "Awaria (Reply does not match to requested pattern)",
      "duration" : 652,
      "end_time" : null,
      "first_analysis_id" : "148555590120222",
      "pause_reason" : null,
      "service_id" : 111,
      "start_time" : "2017-01-27T22:25:06Z",
      "status" : "failure"
   }
]

Dostępność usługi

Pobranie dostępności usługi (danych Service Level) z wybranego przedziału czasowego:

curl -u USERNAME:PASSWORD \
   'https://api.monit24.pl/v3/services/108/history/service_level?from=2017-01-01T00:00:00Z&to=2017-02-01T00:00:00Z'
{
   "failure" : 700151,
   "ok" : 167685,
   "paused" : 21669
}

Wynik zawiera sumaryczną liczbę sekund, w których usługa działała poprawnie, błędnie i w których monitoring był zatrzymany.