نظرة عامة على نقل البيانات

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

أفضل الممارسات المتعلّقة بالفوترة لنقل البيانات

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

تفعيل Places API

تعتمد فئة Place على خدمة Places API. لاستخدام ميزات فئة "المكان" الجديدة، عليك أولاً تفعيل Places API (الإصدار الجديد) في مشروعك على Google Cloud. لمزيد من المعلومات، يُرجى الاطّلاع على البدء.

التغييرات العامة

يسرد الجدول التالي بعض الاختلافات الرئيسية بين PlacesService وPlace:

PlacesService (قديمة) Place (ميزة جديدة)
تتطلّب الطرق استخدام دالة ردّ اتصال لمعالجة عنصر النتائج google.maps.places.PlacesServiceStatus الاستجابة. يستخدم وعدًا، ويعمل بشكل غير متزامن.
تتطلّب الطرق وضع علامة PlacesServiceStatus. لا يلزم التحقّق من الحالة، ويمكن استخدام معالجة الأخطاء العادية.
يتم تنسيق حقول بيانات الأماكن باستخدام أسلوب الكتابة بترتيب أبجدي معكوس. يتم تنسيق حقول بيانات الأماكن باستخدام أسلوب الكتابة بحرف القاف.
تقتصر على مجموعة ثابتة من أنواع الأماكن وحقول بيانات الأماكن. يوفّر هذا الإصدار مجموعة موسّعة من أنواع الأماكن وحقول بيانات الأماكن التي يتم تعديلها بانتظام.

التغييرات المتعلّقة بواجهة برمجة التطبيقات

توفّر فئة Place واجهة برمجة تطبيقات لاستخدام مكتبة Places، كما تتيح أنماط الاستخدام الحديثة، مثل Promises. تعرض فئة Place حقول بيانات الأماكن وأنواع الأماكن نفسها التي تعرضها خدمة Places Service القديمة، كما تتضمّن العديد من القيم الجديدة لأنواع الأماكن وحقول بياناتها.

يوضِّح هذا الجدول كيفية ربط ميزات خدمة "الأماكن" بميزات فئة "المكان":

خدمة "الأماكن" (الإصدار القديم) فئة المكان (جديد)
حقول بيانات الأماكن حقول بيانات فئة الأماكن
أنواع الأماكن أنواع الأماكن
PlacesService.findPlaceFromQuery() Place.searchByText()
PlacesService.findPlaceFromPhoneNumber() Place.searchByText()
PlacesService.textSearch() Place.searchByText()
PlacesService.nearbySearch() Place.searchNearby()
PlacesService.getDetails() Place.fetchFields()
Places.AutocompletionRequest Places.AutocompleteRequest
Places.AutocompletePrediction Places.PlacePrediction
صف Autocomplete صف PlaceAutocompleteElement
صف SearchBox ---

تحميل مكتبة "الأماكن"

تعتمد طريقة تحميل تطبيقك لـ "مكتبة الأماكن" على أداة تحميل التمهيد التي يتم استخدامها. إذا كان تطبيقك يستخدم استيراد المكتبات الديناميكية، يمكنك تحميل المكتبات المطلوبة أثناء التشغيل باستخدام عامل التشغيل await لمحاولة استدعاء importLibrary()، كما هو موضّح هنا:

const { Place } = await google.maps.importLibrary("places");

إذا كان تطبيقك يستخدم علامة تحميل النص البرمجي المباشر، اطلب مكتبة places في نص التحميل:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

مزيد من المعلومات عن تحميل واجهة برمجة التطبيقات JavaScript API في "خرائط Google"

يتضمّن هذا القسم الأدلة التالية لمساعدتك في نقل بيانات تطبيقاتك لاستخدام أحدث إصدار من Places API: