التشغيل السريع: إنشاء تطبيق أندرويد باستخدام خرائط Azure.

توضح لك هذه المقالة كيفية إضافة خرائط Azure إلى تطبيق Android. فهو يرشدك إلى هذه الخطوات الأساسية:

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

إشعار

خرائط Azure إيقاف Android SDK

تم الآن إهمال خرائط Azure Native SDK لنظام التشغيل Android وسيتم إيقافه في 3/31/25. لتجنب انقطاع الخدمة، قم بالترحيل إلى خرائط Azure Web SDK بحلول 3/31/25. لمزيد من المعلومات، راجع دليل ترحيل خرائط Azure Android SDK.

المتطلبات الأساسية

1. اشتراك في منصة Microsoft Azure. في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

2. Android Studio. إذا لم يكن لديك Android Studio، يمكنك الحصول عليه مجانًا من Google.

إشعار

تم إنشاء العديد من التعليمات في هذا التشغيل السريع باستخدام Android Studio Arctic Fox (2020.3.1). إذا كنت تستخدم إصدارًا مختلفًا من Android Studio، فقد تختلف الخطوات الخاصة بـ Android Studio.

أنشئ حساب خرائط Azure

إنشاء حساب جديد لخرائط Azure بالخطوات التالية:

1. في الزاوية العلوية اليسرى من مدخل Microsoft Azure، حدد Create a resource.

2. في المربع Search the Marketplace، اكتب Azure Maps، ثم حدد Azure Maps من نتائج البحث.

3. حدد زر إنشاء.

4. في الصفحة "إنشاء حساب الخرائط"، أدخِل القيم التالية:

   • الاشتراك الذي تريد استخدامه لهذا الحساب.
   • اسم "مجموعة الموارد" لهذا الحساب. يمكنك اختيار إنشاء مجموعةموارد جديدة أو استخدام الموارد الموجودة.
   • اسم حسابك الجديد.
   • مستوى التسعير لهذا الحساب. حدد Gen2.
   • اقرأ الشروط، وتحقق من خانة الاختيار للتأكد من أنك قرأت بيان الترخيص والخصوصية ووافقت عليه.
   • انقر فوق زر مراجعة + إنشاء.
   • بمجرد التأكد من صحة كل شيء في صفحة Review + create ، حدد الزر Create .

   

الحصول على مفتاح الاشتراك لحسابك

بمجرد إنشاء حساب خرائط Azure بنجاح، قم باسترداد مفتاح الاشتراك الذي يمكنك من الاستعلام عن واجهات برمجة تطبيقات الخرائط.

1. افتح حساب Azure Maps الخاص بك في المدخل.
2. في الجزء الأيمن، حدد Authentication.
3. انسخ Primary Key واحفظه محليًا لاستخدامه لاحقًا في هذا البرنامج التعليمي.

إشعار

لأغراض الأمان، يوصى بالتدوير بين المفاتيح الأساسية والثانوية. لتبديل المفاتيح، قم بتحديث التطبيق لاستخدام المفتاح الثانوي، ونشره، ثم اضغط على زر الدورة/التحديث بجانب المفتاح الأساسي لإنشاء مفتاح أساسي جديد. سيتم تعطيل المفتاح الأساسي القديم. لمزيد من المعلومات حول تدوير المفتاح، راجع إعداد Azure Key Vault مع تدوير المفتاح والتدقيق.

أنشئ مشروعًا في أستوديو أندرويد

أكمل الخطوات التالية لإنشاء مشروع جديد مع نشاط فارغ في Android Studio:

1. ابدأ تشغيل Android Studio وحدد New من القائمة File، ثم New Project...

2. في شاشة New Project، حدد Phone and Tablet من قائمة Templates على الجانب الأيسر من الشاشة.

   

3. حدد Empty Activity من قائمة القوالب، ثم Next.

   

4. في شاشة نشاط فارغ، أدخل قيم الحقول التالية:

   • الاسم. أدخل AzureMapsApp.
   • اسم الحزمة. استخدم com.example.azuremapsapp الافتراضي.
   • موقع الحفظ. استخدم الإعداد الافتراضي أو حدد موقعًا جديدًا لحفظ ملفات المشروع. تجنب استخدام المسافات في المسار أو اسم الملف بسبب المشاكل المحتملة مع أدوات NDK.
   • اللغة. حدد Kotlin أو Java.
   • الحد الأدنى من SDK. حدد API 21: Android 5.0.0 (Lollipop) كحد أدنى SDK. إنه أقدم إصدار يدعمه خرائط Azure Android SDK.

5. حدد Finish لإنشاء المشروع.

راجع وثائق أستوديو أندرويد للحصول على مزيد من المساعدة في تثبيت أستوديو أندرويد وإنشاء مشروع جديد.

الاتصال بالشبكة الظاهرية

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

لإعداد جهاز ظاهري يعمل بنظام Android (AVD):

1. حدد AVD Manager في القائمة Tools .
2. يظهر إدارة الأجهزة الظاهري لنظام التشغيل Android. حدد Create Virtual Device.
3. في فئة الهواتف، حدد Nexus 5X، ثم حدد التالي.

لمزيد من المعلومات حول إعداد AVD، راجع إنشاء وإدارة الأجهزة الظاهرية في وثائق Android Studio.

قم بتثبيت Azure Maps Android SDK

الخطوة التالية في بناء التطبيق الخاص بك هي تثبيت Azure Maps Android SDK. أكمل هذه الخطوات لتثبيت SDK:

1. افتح ملف إعدادات المشروع settings.gradle وأضف التعليمات البرمجية التالية إلى قسم repositories :

   maven {url "https://atlas.microsoft.com/sdk/android"}
   

2. في نفس إعدادات المشروع ملف settings.gradle، قم بتغيير repositoriesMode إلى PREFER_SETTINGS:

   repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
   

   يجب أن يظهر ملف إعدادات المشروع الآن كما يلي:

   

3. افتح ملف gradle.properties للمشروع، وتحقق من تعيين android.useAndroidX و android.enableJetifier على true.

   إذا لم يتضمن android.useAndroidX ملف gradle.properties وandroid.enableJetifier، أضف الخطين التاليين إلى نهاية الملف:

   android.useAndroidX=true
   android.enableJetifier=true
   

4. افتح ملف application build.gradle وقم بما يلي:

   1. تحقق من أن minSdk الخاص بمشروعك هو 21 أو أعلى.

   2. تأكد من أن في compileOptionsالقسم Android كما يلي:

      compileOptions {
          sourceCompatibility JavaVersion.VERSION_1_8
          targetCompatibility JavaVersion.VERSION_1_8
      }
      

   3. قم بتحديث كتلة التبعيات الخاصة بك وأضف سطر تبعية تنفيذ جديدًا لأحدث إصدار من Azure Maps Android SDK:

      implementation 'com.azure.android:azure-maps-control:1.+'
      

   4. حدد Sync Project with Gradle Files من القائمة File .

   

5. إضافة جزء خريطة إلى النشاط الرئيسي:

   <com.azure.android.maps.control.MapControl
       android:id="@+id/mapcontrol"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       />
   

   لتحديث النشاط الرئيسي، حدد app > res > layout >activity_main.xml في Project navigator:

   

6. في ملف MainActivity.java :

   • إضافة الواردات لـ Azure Maps SDK
   • تعيين معلومات مصادقة Azure Maps
   • الحصول على مثيل عنصر تحكم الخريطة في أسلوب onCreate

   تلميح

   من خلال تعيين معلومات المصادقة بشكل عام في الفئة AzureMaps باستخدام الأسلوبين setSubscriptionKey أو setAadProperties، لن تحتاج إلى إضافة معلومات المصادقة الخاصة بك في كل طريقة عرض.

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

   • onCreate(Bundle)
   • onDestroy()
   • onLowMemory()
   • onPause()
   • onResume()
   • onSaveInstanceState(Bundle)
   • onStart()
   • onStop()

   تحرير الملف MainActivity.java كما يلي:

   package com.example.azuremapsapp;
   
   import androidx.appcompat.app.AppCompatActivity;
   import android.os.Bundle;
   import com.azure.android.maps.control.AzureMaps;
   import com.azure.android.maps.control.MapControl;
   import com.azure.android.maps.control.layer.SymbolLayer;
   import com.azure.android.maps.control.options.MapStyle;
   import com.azure.android.maps.control.source.DataSource;
   
   public class MainActivity extends AppCompatActivity {
   
   static {
       AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");
   
       //Alternatively use Azure Active Directory authenticate.
       //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
   }
   
   MapControl mapControl;
   
   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       mapControl = findViewById(R.id.mapcontrol);
   
       mapControl.onCreate(savedInstanceState);
   
       //Wait until the map resources are ready.
       mapControl.onReady(map -> {
   
           //Add your post map load code here.
   
       });
   }
   
   @Override
   public void onResume() {
       super.onResume();
       mapControl.onResume();
   }
   
   @Override
   protected void onStart(){
       super.onStart();
       mapControl.onStart();
   }
   
   @Override
   public void onPause() {
       super.onPause();
       mapControl.onPause();
   }
   
   @Override
   public void onStop() {
       super.onStop();
       mapControl.onStop();
   }
   
   @Override
   public void onLowMemory() {
       super.onLowMemory();
       mapControl.onLowMemory();
   }
   
   @Override
   protected void onDestroy() {
       super.onDestroy();
       mapControl.onDestroy();
   }
   
   @Override
   protected void onSaveInstanceState(Bundle outState) {
       super.onSaveInstanceState(outState);
       mapControl.onSaveInstanceState(outState);
   }}
   

7. في الملف MainActivity.kt :

   • إضافة الواردات لـ Azure Maps SDK
   • تعيين معلومات مصادقة Azure Maps
   • الحصول على مثيل عنصر تحكم الخريطة في أسلوب onCreate

   تلميح

   من خلال تعيين معلومات المصادقة بشكل عام في الفئة AzureMaps باستخدام الأسلوبين setSubscriptionKey أو setAadProperties، لن تحتاج إلى إضافة معلومات المصادقة الخاصة بك في كل طريقة عرض.

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

   • onCreate(Bundle)
   • onDestroy()
   • onLowMemory()
   • onPause()
   • onResume()
   • onSaveInstanceState(Bundle)
   • onStart()
   • onStop()

   تحرير الملف MainActivity.kt كما يلي:

   package com.example.azuremapsapp;
   
   import androidx.appcompat.app.AppCompatActivity
   import android.os.Bundle
   import com.azure.android.maps.control.AzureMap
   import com.azure.android.maps.control.AzureMaps
   import com.azure.android.maps.control.MapControl
   import com.azure.android.maps.control.events.OnReady
   
   class MainActivity : AppCompatActivity() {
   
       companion object {
           init {
               AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");
   
               //Alternatively use Azure Active Directory authenticate.
               //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
           }
       }
   
       var mapControl: MapControl? = null
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
           setContentView(R.layout.activity_main)
   
           mapControl = findViewById(R.id.mapcontrol)
   
           mapControl?.onCreate(savedInstanceState)
   
           //Wait until the map resources are ready.
           mapControl?.onReady(OnReady { map: AzureMap -> })
       }
   
       public override fun onStart() {
           super.onStart()
           mapControl?.onStart()
       }
   
       public override fun onResume() {
           super.onResume()
           mapControl?.onResume()
       }
   
       public override fun onPause() {
           mapControl?.onPause()
           super.onPause()
       }
   
       public override fun onStop() {
           mapControl?.onStop()
           super.onStop()
       }
   
       override fun onLowMemory() {
           mapControl?.onLowMemory()
           super.onLowMemory()
       }
   
       override fun onDestroy() {
           mapControl?.onDestroy()
           super.onDestroy()
       }
   
       override fun onSaveInstanceState(outState: Bundle) {
           super.onSaveInstanceState(outState)
           mapControl?.onSaveInstanceState(outState)
       }
   }
   

8. حدد زر التشغيل من شريط الأدوات، كما هو موضح في الصورة التالية (أو اضغط Control + R على Mac)، لإنشاء التطبيق.

   

يستغرق Android Studio بضع ثوان لبناء التطبيق. بعد اكتمال البناء، يمكنك اختبار التطبيق الخاص بك في جهاز Android الذي تمت محاكاته. يجب أن تشاهد خريطة مثل هذه:

تلميح

بشكل افتراضي، يعيد Android تحميل النشاط عند تغيير الاتجاه أو إخفاء لوحة المفاتيح. يؤدي هذا إلى إعادة تعيين حالة الخريطة (إعادة تحميل الخريطة التي تعيد تعيين طريقة العرض وتعيد تحميل البيانات إلى الحالة الأولية). لمنع حدوث ذلك، أضف ما يلي إلى mainfest: android:configChanges="orientation|keyboardHidden". سيؤدي ذلك إلى منع النشاط من إعادة التحميل والاستدعاء onConfigurationChanged() بدلا من ذلك عند تغيير الاتجاه أو إخفاء لوحة المفاتيح.

تنظيف الموارد

تحذير

توضح البرامج التعليمية المدرجة في قسم "الخطوات التالية" بالتفصيل كيفية استخدام Azure Maps وتكوينها مع حسابك. لا تقم بتنظيف الموارد التي تم إنشاؤها في هذه البداية السريعة إذا كنت تخطط لمتابعة الدروس.

إذا كنت لا تخطط لمتابعة الدروس، واتخاذ هذه الخطوات لتنظيف الموارد:

1. أغلق استوديو Android واحذف التطبيق الذي أنشأته.
2. إذا قمت باختبار التطبيق على جهاز خارجي، فألغِ تثبيت التطبيق من على هذا الجهاز.

إذا كنت لا تخطط لمواصلة التطوير باستخدام Azure Maps Android SDK:

1. انتقل إلى صفحة مدخل Azure. حدد "كافة الموارد" من صفحة المدخل الرئيسية.
2. حدد حساب خرائط Azure. في الجزء العلوي من الصفحة، حدد حذف.
3. اختياريًّا ، إذا كنت لا تخطط لمواصلة تطوير تطبيقات Android ، فقم بإلغاء تثبيت Android Studio.

لمزيد من أمثلة التعليمات البرمجية، راجع هذه الأدلة:

• إدارة المصادقة في خرائط Azure
• تغيير أنماط الخريطة في خرائط أندرويد
• إضافة طبقة رمز
• إضافة طبقة خط
• إضافة طبقة مضلعة

الخطوات التالية

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

البرنامج التعليمي: تحميل بيانات GeoJSON في خرائط Azure Android SDK