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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

تفعيل Places API

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

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

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

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

التغييرات الخاصة بواجهة برمجة التطبيقات

توفّر فئة Place واجهة برمجة تطبيقات لاستخدام مكتبة الأماكن، وتتيح أنماط الاستخدام الحديثة، مثل 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>

مزيد من المعلومات حول تحميل Maps JavaScript API

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