أمثلة REST API

يحتوي القسم التالي على أمثلة لنصوص bash البرمجية حول كيفية تنفيذ الإجراءات باستخدام واجهة SKOOR REST API مع الأداة المساعدة curl. تتم تهيئة معظم المدخلات والمخرجات بتنسيق JSON. لسهولة القراءة، تم استخدام محلل JSON jq في بعض الأمثلة، والذي يمكن تثبيته من مستودعات Redhat أو CentOS الشائعة.

رأس نص Bash البرمجي

المعلمات الشائعة التي يجب تعيينها كرأس لنص bash البرمجي في أمثلة النصوص البرمجية أدناه (يجب تعديل USER و PASSWORD لتتوافق مع مستخدم SKOOR حقيقي):

#!/bin/bash
HOST=reltest
USER=admin
PASSWORD=admin

أمثلة الطلبات

يمكن نسخ ولصق الطلبات ونصوص الطلبات الواردة في الأمثلة أدناه كما هي، باستثناء معرفات الكائنات التي يجب استبدالها بمعرفات موجودة على النظام الذي تُنفذ عليه الطلبات. يجب توفير أجزاء من نصوص الطلبات حتى لو لم تكن تحتوي على قيم ذات دلالة لإنشاء الكائن أو تحديثه.

يجب توفير معظم معلومات التاريخ والوقت في الطلبات بتنسيق ISO 8601 وتنسيق المدة الزمنية

جلسة SKOOR

تسجيل الدخول إلى SKOOR:

SESSION_ID=$(curl --silent -k "https://$HOST/skoor-webservice/session/login?username=$USER&password=$PASSWORD" | jq -r '.sessionId') >/dev/null

يرجى تسجيل الخروج دائمًا بعد الانتهاء من جميع الطلبات، وإلا فستظل الجلسات مفتوحة لمدة 24 ساعة

تسجيل الخروج:

curl -k "https://$HOST/skoor-webservice/session/logout?sessionId=$SESSION_ID"

المستخدمون

الاستعلام عن جميع مستخدمي SKOOR وتحليل الأسماء والأدوار باستخدام jq:

curl --silent -k "https://$HOST/skoor-webservice/users?sessionId=$SESSION_ID" | jq -r '.[] | "\(.name) \(.role)"'

المجموعات

الاستعلام عن مجموعة محددة بالمعرف 495:

curl -k -X GET "https://$HOST/skoor-webservice/groups/495?sessionId=$SESSION_ID"

الاستعلام عن مجموعة باستخدام عامل تصفية بحث مرمز بترميز URL. يجب أن تحتوي النتيجة على جميع المجموعات الموجودة أسفل المجموعة الأصل ذات المعرف 207.

عامل تصفية البحث الأصلي: المجموعات ذات المعرف الذي لا يساوي 207:

{"type":"group","mode": "and","conditions": [{"item":"id","operator": "ne","expression":"207"}]}

عامل تصفية البحث المرمز بترميز URL (يمكن إجراء الترميز/فك الترميز باستخدام مهمة SKOOR HTTP أو إحدى الخدمات المتعددة على الإنترنت):

%7B%22type%22%3A%22group%22%2C%22mode%22%3A%20%22and%22%2C%22conditions%22%3A%20%5B%7B%22item%22%3A%22id%22%2C%22operator%22%3A%20%22ne%22%2C%22expression%22%3A%22207%22%7D%5D%7D

الاستعلام:

curl -k -X GET "https://$HOST/skoor-webservice/groups/207/search?filterDefinition=%7B%22type%22%3A%22group%22%2C%22mode%22%3A%20%22and%22%2C%22conditions%22%3A%20%5B%7B%22item%22%3A%22id%22%2C%22operator%22%3A%20%22ne%22%2C%22expression%22%3A%22207%22%7D%5D%7D&sessionId=$SESSION_ID"

الأجهزة

الاستعلام عن جهاز بالمعرف 383:

curl -k -X GET "https://$HOST/skoor-webservice/devices/383?sessionId=$SESSION_ID"

إنشاء جهاز أسفل المجموعة ذات المعرف 308:

نص الطلب لإنشاء جهاز من النوع الفرعي server بالاسم SKOOR Server. قم بتعيين المجمع الافتراضي إلى المعرف 2 وهو المجمع المحلي:

DEVICE_BODY='{
	"type": "device",
	"subType": "server",
	"name": "SKOOR Server",
	"address": "",
	"netmask": "",
	"deviceName": "localhost",
	"properties": [],
	"parameter": {},
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"isTemplate": false,
	"instanceType": "sub",
	"collectorId": 2,
	"hasChildren": false
}'

الطلب:

echo $DEVICE_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/devices?parentType="group"&parentId="308"&sessionId=$SESSION_ID"

إنشاء مثيل جهاز من قالب أسفل المجموعة ذات المعرف 332. لتحقيق ذلك، سيتم استخدام أسلوب النسخ (copy) في واجهة REST API. يجب تعيين معرف الجهاز (180 في المثال) إلى معرف قالب الجهاز:

curl -k -X POST "https://$HOST/skoor-webservice/devices/180/copy?destinationName="rest-test"&destinationAddress="localhost"&parentType="group"&parentId=332&destinationType="instance"&collectorId=2&jobsStopped=false&sessionId=$SESSION_ID"

حذف الجهاز ذي المعرف 558:

لا يمكن استعادة الكائنات المحذوفة إلا من النسخة الاحتياطية للتكوين!

curl -k -X DELETE "https://localhost/skoor-webservice/devices/558?recursive=true&sessionId=$SESSION_ID"

المهام

الاستعلام عن المهمة ذات المعرف 1675 مع الحدود والقيم:

curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1675?thresholds=true&values=true&sessionId=$SESSION_ID"

البحث عن مهمة باستخدام عامل تصفية بحث.

عامل تصفية بحث مرمز بترميز URL للبحث عن المهام الموجودة أسفل المجموعة ذات المعرف 216 والتي تحتوي على خاصية مخصصة بالمفتاح test_property مضبوطة على القيمة abc:

curl -ks -X GET "https://$HOST/skoor-webservice/groups/216/search?filterDefinition=%7B%22type%22%3A%22job%22%2C%22mode%22%3A%22and%22%2C%22conditions%22%3A%5B%7B%22item%22%3A%22property_key%22%2C%22operator%22%3A%22eq%22%2C%22expression%22%3A%22abc%22%2C%22propertyKey%22%3A%22test_property%22%7D%5D%7D&sessionId=$SESSION_ID"

عامل تصفية بحث نصي عادي للمهام من النوع الفرعي webcollector أسفل المجموعة 310 مع تحليل النتيجة باستخدام jq:

curl -ks -X GET -G "https://$HOST/skoor-webservice/groups/310/search?sessionId=$SESSION_ID" --data-urlencode "filterDefinition={\"type\":\"job\",\"mode\":\"and\",\"conditions\":[{\"item\":\"subType\",\"operator\":\"eq\",\"expression\":\"webcollector\"}]}" | jq -r '.items[] | "\(.deviceName) \(.name) \(.id)"'

إنشاء مهمة أسفل الجهاز ذي المعرف 555:

نص الطلب لإنشاء مهمة من النوع الفرعي webcollector بالاسم TEST generated وثلاث قيم إرجاع. أنشئ المهمة ضمن الجهاز ذي المعرف 555. سيتم تعيين الفاصل الزمني للتنفيذ إلى 0 ثانية (PT0S: بدون فاصل زمني):

JOB_BODY='{
	"type": "job",
	"name": "TEST generated",
	"deviceId": 555,
	"subType": "webcollector",
	"interval": "PT0S",
	"stopped": false,
	"parameters": {
		"intervalMode": 0,
		"filename": "",
		"returnValue": [
			{
				"valueName": "Return value 1"
			},
			{
				"valueName": "Return value 2"
			},
			{
				"valueName": "Return value 3"
			}
		]
	},
	"isTemplate": false,
	"properties": [],
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none",
	"stateForced": false,
	"thresholds": null,
	"values": null,
	"message": null
}'

الطلب:

echo $JOB_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs?parentType="device"&parentId="555"&sessionId=$SESSION_ID"

تحديث المهمة ذات المعرف 1608:

نص الطلب للـ مهمة ذات المعرف 1608 على الجهاز ذي المعرف 555. عيّن الحدود لهذه المهمة:

JOB_BODY_UPDATE='{
	"type": "job",
	"id": 1608,
	"name": "Richmond",
	"deviceId": 555,
	"deviceName": "TEST generated device",
	"subType": "webcollector",
	"interval": "PT0S",
	"stopped": false,
	"parameters": {
		"intervalMode": 0,
		"filename": "",
		"returnValue": [
			{
				"valuePrecision": 3,
				"valueName": "myValue"
			}
		]
	},
	"isTemplate": false,
	"properties": [],
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none",
	"currentState": "ok",
	"stateForced": false,
	"thresholds": {
		"major": {
			"mode": "or",
			"conditions": [
				{
					"key": "returnValue1",
					"operator": ">",
					"value": 60.0,
					"repetition": 1,
					"inFuture": null,
					"adaptiveValues": null
				}
			]
		}
	},
	"values": {},
	"message": null,
	"collectorId": 2
}'

الطلب:

echo $JOB_BODY_UPDATE | curl -s -k -X PUT -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs/1608?sessionId=$SESSION_ID"

إيقاف/بدء المهمة ذات المعرف 1605:

curl -ks -X GET -G "https://$HOST/skoor-webservice/jobs/1605?sessionId=$SESSION_ID" | jq -r '.stopped = false' | curl -s -k -X PUT -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs/1605?sessionId=$SESSION_ID"

الاستعلام عن سجل القيم للمهمة ذات المعرف 1326:

يجب توفير معلومات التاريخ والوقت بتنسيق ISO 8601 وتنسيق المدة الزمنية

curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1326/value-history?timestamp_begin=2018-04-16T08%3A00%3A00Z&timestamp_end=2018-04-16T10%3A00%3A00Z&scale=PT10M&key=returnValue1&mode=avg&values=true&sessionId=$SESSION_ID"

SLC

الاستعلام عن سجل حالة SLC بالمعرف 6:

curl -k -X GET "https://$HOST/skoor-webservice/slcs/6/state-history?timestamp_begin=2017-10-01T00:00%2B01:00&timestamp_end=2017-12-12T23:59%2B01:00&recalc=true&sessionId=$SESSION_ID"

SLO

الاستعلام عن SLO بالمعرف 116:

curl -k -X GET "https://$HOST/skoor-webservice/slos/116?sessionId=$SESSION_ID"

الاستعلام عن سجل الحالة لـ SLO ذي المعرف 116:

curl -k -X GET "https://$HOST/skoor-webservice/slos/116/state-history?timestamp_begin=2018-01-01T00:00%2B01:00&timestamp_end=2018-12-12T23:59%2B01:00&recalc=true&sessionId=$SESSION_ID"

الاستعلام عن الكائنات الفرعية لـ SLO ذي المعرف 176:

curl -k -X GET "https://$HOST/skoor-webservice/slos/176/children?sessionId=$SESSION_ID"

إنشاء SLO أسفل المجموعة ذات المعرف 296:

نص الطلب لإنشاء SLO من النوع الفرعي top بالاسم TEST SLO:

SLO_BODY='{
	"type": "slo",
	"subType": "top",
	"name": "TEST SLO",
	"deviceId": 0,
	"deviceName": "",
	"stateOperation": "and",
	"pushState": "any",
	"sortMode": "link",
	"warning": 0,
	"minor": 0,
	"major": 0,
	"minorWarning": 0,
	"minorMinor": 0,
	"warningWarning": 0,
	"isTemplate": false,
	"ignoreMaintenance": true,
	"isReason": true,
	"properties": [],
	"parameters": {
		"children": 0,
		"costsPerMin": 0,
		"currency": "",
		"riskFactor": 0
	},
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none"
}'

الطلب:

echo $SLO_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/slos?parentType=group&parentId=296&sessionId=$SESSION_ID"

إنشاء مثيل SLO من قالب SLO ذي المعرف 179. سيكون اسم SLO هو rest-test-slo وسيكون الكائن الأصل هو slo ذو المعرف 177:

curl -k -X POST "https://$HOST/skoor-webservice/slos/179/copy?destinationName=rest-test-slo_1&parentType=slo&parentId=177&destinationType=instance&sessionId=$SESSION_ID"

الانقطاعات

الاستعلام عن الانقطاعات بين 2019-02-21T09:00+01:00 و 2019-03-21T23:59+01:00 (مرمزة بترميز URL). الإعداد الافتراضي هو حد أدنى للمدة قدره 10 دقائق (PT10M) وحالة Major فقط:

curl -k -X GET "https://$HOST/skoor-webservice/devices/383/outages?begin=2019-02-21T09:00%2B01:00&end=2019-03-21T23:59%2B01:00&recalc=false&sessionId=$SESSION_ID"

إعادة التقييم

الاستعلام عن عمليات إعادة التقييم للمجموعة 207 بدءًا من 2019-04-01T00:00:00Z:

curl -k -X GET "https://$HOST/skoor-webservice/groups/207/revaluations?begin=2019-04-01T00:00:00Z&sessionId=$SESSION_ID"

إضافة إعادة تقييم إلى المجموعة ذات المعرف 207:

يجب تعيين المعلمتين begin و end بالتوقيت العالمي المنسق (UTC) متبوعًا بالمنطقة الزمنية Z أو +00:00 أو بالتوقيت المحلي متبوعًا بالمنطقة الزمنية (مثل +02:00). تؤثر المعلمة timezone فقط على مصفوفة times

إذا لم يتطابق وقت المعلمة begin مع وقت البدء في مصفوفة times، فلن يتم عرض الصيانة إلا في وضع التحرير (Edit revaluation). يرجى ملاحظة أن توقيت MET سيميز تلقائيًا بين التوقيت الصيفي والشتوي. عيّن وقت البدء إلى التوقيت المحلي في هذه الحالة

نص الطلب لإجراء إعادة تقييم لمرة واحدة من 2019-04-13T07:20:00Z إلى 2019-04-13T08:20:00Z:

REVALUATION_BODY='{
	"begin": "2019-04-13T07:20:00Z",
	"end": "2019-04-13T08:20:00Z",
	"created": null,
	"type": "maintenance",
	"adjustTo": "undefined",
	"inPast": null,
	"incident": null,
	"name": "Test-Maintenance",
	"active": [
		{
			"type": "one_time",
			"name": null,
			"timezone": "UTC",
			"times": [
				{
					"begin": "07:20",
					"duration": "PT1H",
					"date": "2019-04-13"
				}
			],
			"exception": false
		}
	]
}'

الطلب:

echo $REVALUATION_BODY | curl -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/groups/207/revaluations?sessionId=$SESSION_ID"