تمكن إدارة Portal for ArcGIS ببساطة من خلال طلبات إلى ArcGIS REST API. حتى عند استخدام موقع Portal for ArcGIS على الويب لإدارة البوابة الإلكترونية، فإنه يتم إجراء الاستدعاءات إلى API في الخلفية. لكتابة البرامج النصية التي تدير Portal for ArcGIS، يتعين عليك اختيار لغة برنامج نصي يتيح لك إنشاء عناوين URL، وإنشاء طلبات HTTP، وتحليل استجابات HTTP. تستخدم الأمثلة في نظام التعليمات هذا Python.
من الضروري ملاحظة أن استخدام API لا يتطلّب وجود أي برنامج من برامج Esri على الجهاز الذي تقوم بتشغيل البرنامج النصي من خلاله. فكل ما يلزمك هو بيئة يمكنك فيها إنشاء طلبات HTTP إلى البوابة الإلكترونية.
بدء استخدام إدارة البوابة الإلكترونية باستخدام ArcGIS REST API
ولاستخدام ArcGIS REST API، فإنك تقوم بإنشاء طلب HTTP للعملية التي تريد تنفيذها، كما تقوم بتضمين المعلمات المطلوبة لتلك العملية. ويعد استخدام دليل Portal for ArcGIS طريقة بسيطة للتعرف على العمليات الإدارية المتوفرة ومعلماتها المطلوبة.
استخدام دليل Portal for ArcGIS
يكون دليل Portal for ArcGIS متاح خلال اثنين من تطبيقات الويب ويمكن المساعدة في فهم كيفية كتابة البرامج النصية الإدارية للبوابة الإلكترونية. يُعد دليل Portal for ArcGIS من الناحية التصورية مشابهًا لدليل مسؤول ArcGIS for Server ودليل الخدمات. تتنوع المهام المتوفرة بين التطبيقات، كما ذُكِر في نبذة عن دليل Portal for ArcGIS. يتم تنسيق عناوين URL للتطبيقات كما يلي:
- https://webadaptorhost.domain.com/webadaptorname/portaladmin
- https://webadaptorhost.domain.com/webadaptorname/sharing/rest
تعامل مع دليل ArcGIS Portal Directory على أنه قائمة من موارد Portal for ArcGIS المعروضة من خلال REST API. يمكن الانتقال إلى الروابط في دليل Portal for ArcGIS لمعرفة عناوين URL والمعلمات المُراد استخدامها في طلبات خدمة الويب الإدارية. ويمكن بعد ذلك صياغة تلك الطلبات وإرسالها عبر HTTP باستخدام لغة برمجة من اختيارك.
حاول استخدام دليل Portal for ArcGIS لتنفيذ مهمة إدارية ما. انتبه للمعطيات التي يتعين عليك إدخالها وافحص عنوان URL الذي يوجد في شريط عنوان المستعرض عند إجراء طلب الخادم. ويمكن أن تكون أدوات مُطور الويب مثل Fiddler وFirebug أدواتٍ عملية لرؤية النص الأساسي الكامل للطلب والاستجابة. وتُعد هذه المعلومات قيّمة للغاية عند محاولة إنشاء طلبات HTTP الإدارية من خلال Python أو أي لغة برمجة نصية أخرى.
وعلى الرغم من أنه يمكن استخدام دليل Portal for ArcGIS بشكل تفاعلي لتنفيذ المعالم الإدارية فعليًا، إلا أنه يمكن استخدامه بشكل أفضل على الإطلاق كأداة تعليمية للمساعدة في التعرف على REST API. ويكون تطبيق إدارة البوابة الإلكترونية المقصود على الويب هو موقع Portal for ArcGIS على الويب.
الحصول على رمز مميز في البرامج النصية واستخدامها
عند إدارة البوابة الإلكترونية خلال موقعها على الويب أو دليل Portal for ArcGIS، سيتعين توفير اسم المستخدم وكلمة المرور للحساب الذي يملك الامتيازات المناسبة للبوابة الإلكترونية. وينطبق المفهوم نفسه عند كتابة البرامج النصية.
ومع ذلك، على عكس الوصول إلى موقع البوابة الإلكترونية على الويب أو دليل ArcGIS Portal Directory حيث سيتعامل المستعرض بشفافية مع عملية المصادقة، يجب أن تفهم كيفية حدوث المصادقة عند استخدام البرامج النصية لإدارة البوابة الإلكترونية.
عند تكوين البوابة الإلكترونية لاستخدام الحسابات الداخلية وكذلك مصادقة الرموز الفريدة، ستصبح قادرًا على استخدام البرامج النصية مع نفس الحسابات الإدارية وكذلك عناوين URL التي يتم استخدامها من دليل Portal for ArcGIS. عند تكوين البوابة الإلكترونية مع عمليات تسجيل الدخول الخاصة بالمؤسسة وكذلك مصادقة الويب الأساسية، يُوصي الحصول على البرامج الأساسية لمحول الويب واستخدام حساب المسؤول الأولي الذي تم إنشاءه بعد تثبيت Portal for ArcGIS.
في حالات أخرى، ستقوم البوابة الإلكترونية بإرجاع الرموز الفريدة، والتي تكون سلاسل خاصة من الأحرف التي تتصل بالبوابة الإلكترونية التي تمت مصادقتها للقيام بإجراءات محددة. كما يجب تضمين هذا الرمز المميز في أي طلبات خدمة ويب تقوم بإجرائها إلى في البوابة الإلكترونية.
تتطلّب دالة Python التالية رمزًا مميزًا. يتم تقديم عنوان URL للبوابة الإلكترونية واسم المستخدم وكلمة المرور على شكل وسيطات.
def generateToken(username, password, portalUrl):
'''Retrieves a token to be used with API requests.'''
parameters = urllib.urlencode({'username' : username,
'password' : password,
'client' : 'referer',
'referer': portalUrl,
'expiration': 60,
'f' : 'json'})
response = urllib.urlopen(portalUrl + '/sharing/rest/generateToken?',
parameters).read()
try:
jsonResponse = json.loads(response)
if 'token' in jsonResponse:
return jsonResponse['token']
elif 'error' in jsonResponse:
print jsonResponse['error']['message']
for detail in jsonResponse['error']['details']:
print detail
except ValueError, e:
print 'An unspecified error occurred.'
print eولا يستمر الرمز المميز إلى الأبد، إلا أنه صُمّم كمهلة زمنية حتى لا يمكن لمستخدم ضار سرقته أو استخدامه لأجل غير مُسمى. نمطيًا، يتعين طلب رموز فريدة جديدة في كل مرة يتم فيها إنشاء البرنامج النصي (لكن ليس كل مرة يتم فيها إنشاء طلبًا). في بعض الحالات الإستثنائية، يمكن انتهاء صلاحية الرموز الفريدة قبل نهاية البرامج النصية. إذا تضمن الطلب رموز فريدة منتهية الصلاحية، ستتضمن استجابة الخادم خطا يشير إلى انتهاء صلاحية هذه الرموز الفريدة. إذا حدث هذا، فعليك بتحديث الرمز المميز الخاص بك وتابع تنفيذ البرنامج النصي الخاص بك.
التعامل مع الطلبات والاستجابات
لإجراء طلب خدمة ويب، يتعين عليك صياغة عنوان URL للحدث المُراد إجراؤه وكذلك المعلمات اللازمة لذلك الإجراء. يُعد الرمز المميز أحد المعلمات المطلوبة في بوابة إلكترونية مُؤمنة مثل تلك التي تم إنشاؤها أعلاه.
وتُقدم جميع الأحداث الإدارية استجابة خدمة ويب ستقوم بطلبها نمطيًا بتنسيق JavaScript Object Notation (JSON). ويوجد لدى لغات البرمجة النصية مثل Python مكتبات تعمل على تحليل أو قراءة استجابة JSON. وقد تريد في بعض الأحيان الحصول على كود حالة HTTP فقط لاكتشاف نجاح الطلب (على سبيل المثال، الكود 200 يعني أنه قد نجح). وفي أحيان أخرى، قد تحتوي الاستجابة على بيانات مثل رسائل السجّل التي تريد تحليلها وفحصها بشكل أكبر.
راجع أمثلة الرمز المتنوعة في كتاب التعليمات للتعرف على كيفية إرساله طلب بصورة برمجية إلى Portal for ArcGIS والتعامل مع الاستجابة.