البرمجة باستخدام ArcGIS REST API

Portal for ArcGIS يمكن أن يتم إدراتها ببساطة من خلال طلبات إلى ArcGIS REST API. حتى عند استخدام موقع Portal for ArcGIS على الويب لإدارة البوابة الإلكترونية، فإنه يتم إجراء الاستدعاءات إلى API في النهاية الخلفية. لكتابة البرامج النصية التي تدير Portal for ArcGIS, يتعين عليك اختيار لغة برنامج نصي يتيح لك إنشاء عناوين URL، وإنشاء طلبات HTTP، وتحليل استجابات HTTP. ويتم استخدام البايثون في الأمثلة الواردة في نظام التعليمات التالي.

من الضروري ملاحظة أن استخدام 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

تعامل مع دليل Portal for ArcGIS على أنها قائمة من موارد Portal for ArcGIS المعروضة من خلال REST API. يمكن الانتقال إلى الروابط في دليل Portal for ArcGIS لمعرفة عناوين URL والمعلمات المُراد استخدامها في طلبات خدمة الويب الإدارية. ويمكن بعد ذلك صياغة تلك الطلبات وإرسالها عبر HTTP باستخدام لغة برمجة من اختيارك.

حاول استخدام دليل Portal for ArcGIS لتنفيذ مهمة إدارية ما. انتبه للمعطيات التي يتعين عليك إدخالها وافحص عنوان URL الذي يوجد في شريط عنوان المستعرض عند إجراء طلب الخادم. ويمكن أن تكون أدوات مُطور الويب مثل Fiddler وFirebug أدواتٍ عملية لرؤية النص الأساسي الكامل للطلب والاستجابة. وتُعد هذه المعلومات قيّمة للغاية عند محاولة إنشاء طلبات HTTP الإدارية من خلال بايثون أو أي لغة برمجة أخرى.

وعلى الرغم من أنه يمكن استخدام دليل Portal for ArcGIS بشكل تفاعلي لتنفيذ المعالم الإدارية فعليًا، إلا أنه يمكن استخدامه بشكل أفضل على الإطلاق كأداة تعليمية للمساعدة في التعرف على REST API. ويكون تطبيق إدارة البوابة الإلكترونية المقصود على الويب هو موقع Portal for ArcGIS على الويب.

الحصول على رمز مميز في البرامج النصية واستخدامها

عند إدارة البوابة الإلكترونية خلال موقعها على الويب أو دليل Portal for ArcGIS، سيتعين توفير اسم المستخدم وكلمة المرور للحساب الذي يملك الامتيازات المناسبة للبوابة الإلكترونية. وينطبق المفهوم نفسه عند كتابة البرامج النصية.

مع ذلك، وبخلاف الوصول إلى موقع البوابة الإلكترونية على الويب أو دليل Portal for ArcGIS حيث سيقوم المستعرض بمعالجة عملية المصادقة، سيتعين فهم كيفية حدوث المصادقة عند استخدام البرامج النصية لإدارة البوابة الإلكترونية.

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

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

تطلّب وظيفة بايثون التالية رمزًا مميزًا. يتم تقديم عنوان 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). ويوجد لدى لغات الترجمة مثل لغة بايثون مكتبات تقوم بتحليل أو قراءة استجابة JSON. وقد تريد في بعض الأحيان الحصول على كود حالة HTTP فقط لاكتشاف نجاح الطلب (على سبيل المثال، الكود 200 يعني أنه قد نجح). وفي أحيان أخرى، قد تحتوي الاستجابة على بيانات مثل رسائل السجّل التي تريد تحليلها وفحصها بشكل أكبر.

راجع أمثلة الكود المتنوعة في كتاب التعليمات للتعرف على كيفية إرساله طلب بصورة برمجية إلى Portal for ArcGIS والتعامل مع الاستجابة.