كيفية دمج واجهات Google البرمجية مع Python وDjango لبناء تطبيق خرائط وعناوين ذكي

مقدمة عملية حول دمج خدمات Google داخل مشاريع Django

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

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

الفكرة الأساسية في التطبيق هي:

• إنشاء حسابات مستخدمين مع حماية النموذج عبر reCAPTCHA v3.
• إتاحة إدخال عنوان المستخدم باستخدام الإكمال التلقائي عبر Google Places API.
• إنشاء مسارات بين عدة نقاط مع عرض الخريطة والاتجاهات التفصيلية.
• دمج JavaScript وAjax مع Django للحصول على تجربة استخدام سلسة.

ما واجهات Google المستخدمة في هذا المشروع؟

يعتمد هذا التطبيق على أكثر من خدمة، وكل خدمة تؤدي دورًا محددًا داخل النظام:

• Google reCAPTCHA v3 لحماية نماذج التسجيل من الإرسال الآلي أو الضار.
• Google Places API لتوقع العناوين أثناء الكتابة.
• Google Directions API لحساب المسارات بين عدة نقاط.
• Google Distance Matrix API لاستخراج المسافات والمدد الزمنية.
• Geocoding API لتحويل العنوان إلى إحداثيات longitude وlatitude.
• Maps JavaScript API لعرض الخرائط مباشرة داخل الواجهة.

خطوات إعداد مفاتيح Google API

إعداد reCAPTCHA v3

لحماية نموذج التسجيل، يجب أولًا إنشاء إعداد جديد في لوحة Google reCAPTCHA. اختر الإصدار v3 لأنه يعتمد على تقييم سلوك المستخدم بدلًا من اختبارات الصور التقليدية.

1. سجّل الدخول بحساب Google.
2. انتقل إلى صفحة إدارة reCAPTCHA.
3. أنشئ موقعًا جديدًا.
4. اختر reCAPTCHA v3.
5. أضف النطاق localhost أثناء التطوير.
6. احفظ Site Key وSecret Key.

من الأفضل التعامل مع Site Key باعتباره معرفًا عامًا للتطبيق، بينما يجب حفظ Secret Key بسرية تامة لأنه يستخدم في التحقق على الخادم.

إنشاء مشروع داخل Google Cloud

بعد ذلك، أنشئ مشروعًا جديدًا داخل Google Cloud Console، ثم أنشئ مفتاح API Key خاصًا به. هذا المفتاح سيستخدم لتفعيل بقية الخدمات المطلوبة.

1. افتح cloud.google.com.
2. أنشئ مشروعًا جديدًا باسم مناسب.
3. انتقل إلى قسم APIs & Services.
4. اختر Credentials.
5. أنشئ API Key.
6. فعّل الواجهات المطلوبة واحدة تلو الأخرى.

الواجهات التي يجب تفعيلها

• Places API
• Directions API
• Distance Matrix API
• Geocoding API
• Maps JavaScript API

يفضل أيضًا تقييد المفتاح حسب النطاقات أو عناوين IP عند الانتقال إلى بيئة الإنتاج، لتقليل مخاطر إساءة الاستخدام.

تهيئة بيئة العمل باستخدام Python وDjango

تثبيت الأدوات الأساسية

قبل بدء البرمجة، تحتاج إلى تثبيت:

• Python
• Django
• بيئة افتراضية مثل virtualenv أو virtualenvwrapper

استخدام البيئة الافتراضية مهم جدًا لعزل الحزم الخاصة بالمشروع عن بقية المشاريع على الجهاز.

إنشاء البيئة الافتراضية وتثبيت Django

بعد فتح الطرفية، يمكن إنشاء البيئة ثم تثبيت Django:

mkvirtualenv django-google-api-tutorial
pip install django

بعد ذلك أنشئ المشروع والتطبيق الأساسي:

django-admin startproject django_google_api_tutorial
cd django_google_api_tutorial
python manage.py startapp main

ضبط إعدادات مشروع Django

بعد إنشاء المشروع، ستحتاج إلى تعديل ملف settings.py ليتعرف على التطبيق الجديد ويخدم الملفات الثابتة والمفاتيح المطلوبة.

إضافة التطبيق إلى INSTALLED_APPS

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'main',
]

إعداد الملفات الثابتة

لأن المشروع يستخدم ملفات CSS وJavaScript وصورًا، يجب تعريف مسارات static files داخل الإعدادات.

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

STATIC_URL = '/static/'
STATICFILES_DIRS = [os.path.join(BASE_DIR, 'static')]
STATIC_ROOT = os.path.join(BASE_DIR, 'static-cdn')

حفظ مفاتيح الواجهات داخل الإعدادات

GOOGLE_API_KEY = 'your_google_api_key'
RECAPTCHA_PUBLIC_KEY = 'your_recaptcha_site_key'
RECAPTCHA_PRIVATE_KEY = 'your_recaptcha_secret_key'
BASE_COUNTRY = 'gb'

في المشاريع الحقيقية، لا يُنصح بوضع هذه القيم مباشرة داخل الملف، بل يفضل تحميلها من متغيرات البيئة باستخدام أدوات مثل django-environ أو python-decouple.

إعداد المسارات داخل Django

الخطوة التالية هي تعريف مسارات التطبيق داخل ملف urls.py الرئيسي:

from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    path('', include('main.urls', namespace='main')),
]

if settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

ثم أنشئ ملف urls.py داخل تطبيق main مع قائمة urlpatterns الأساسية.

بناء الواجهة الخلفية: النماذج، النماذج المرتبطة، والإشارات

إنشاء تطبيق خاص بالمستخدمين

لأن المشروع يعتمد على التسجيل وتسجيل الدخول وإدارة الملف الشخصي، من الأفضل إنشاء تطبيق مستقل للمستخدمين:

python manage.py startapp users

ثم أضفه إلى INSTALLED_APPS.

نموذج الملف الشخصي UserProfile

بدلًا من تعديل نموذج المستخدم الافتراضي مباشرة، يتم إنشاء نموذج إضافي مرتبط به بعلاقة OneToOneField. هذه الطريقة مرنة وتحافظ على بنية المشروع.

from django.db import models
from django.contrib.auth.models import User

class UserProfile(models.Model):
    timestamp = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    address = models.CharField(max_length=100, null=True, blank=True)
    town = models.CharField(max_length=100, null=True, blank=True)
    county = models.CharField(max_length=100, null=True, blank=True)
    postcode = models.CharField(max_length=30, null=True, blank=True)
    country = models.CharField(max_length=100, null=True, blank=True)
    longitude = models.FloatField(null=True, blank=True)
    latitude = models.FloatField(null=True, blank=True)
    captcha_score = models.FloatField(default=0.0)
    has_profile = models.BooleanField(default=False)
    active = models.BooleanField(default=True)

    def __str__(self):
        return f'{self.user}'

هذا النموذج يخزن بيانات الموقع الجغرافي للمستخدم، إضافة إلى نتيجة التحقق من reCAPTCHA.

إنشاء الملف الشخصي تلقائيًا باستخدام signals

حتى لا تضطر لإنشاء سجل الملف الشخصي يدويًا بعد كل تسجيل، يمكن الاستفادة من signals في Django.

from django.db.models.signals import post_save
from django.contrib.auth.models import User
from django.dispatch import receiver
from .models import UserProfile

@receiver(post_save, sender=User)
def create_profile(sender, instance, created, **kwargs):
    if created:
        UserProfile.objects.create(user=instance)

بهذه الطريقة، كلما أُنشئ مستخدم جديد، يُنشأ له ملف شخصي تلقائيًا.

إنشاء النماذج Forms داخل Django

يستخدم المشروع ثلاثة نماذج رئيسية:

• نموذج التسجيل بالاعتماد على UserCreationForm.
• نموذج تسجيل الدخول بالاعتماد على AuthenticationForm.
• نموذج تحديث الملف الشخصي بالاعتماد على ModelForm.

ميزة هذا الأسلوب أنه يختصر منطقًا كبيرًا كان سيتطلب كتابة يدوية، خصوصًا في التعامل مع كلمات المرور والتحقق من صحة المدخلات.

مثال على نموذج الملف الشخصي

from django.forms import ModelForm
from django import forms
from .models import UserProfile

class UserProfileForm(ModelForm):
    address = forms.CharField(required=True, widget=forms.HiddenInput())
    town = forms.CharField(required=True, widget=forms.HiddenInput())
    county = forms.CharField(required=True, widget=forms.HiddenInput())
    postcode = forms.CharField(required=True, widget=forms.HiddenInput())
    country = forms.CharField(required=True, widget=forms.HiddenInput())
    longitude = forms.FloatField(required=True, widget=forms.HiddenInput())
    latitude = forms.FloatField(required=True, widget=forms.HiddenInput())

    class Meta:
        model = UserProfile
        fields = (
            'address', 'town', 'county', 'postcode',
            'country', 'longitude', 'latitude'
        )

استخدام الحقول المخفية هنا مقصود، لأن القيم تُملأ تلقائيًا من Google Places API بعد اختيار العنوان.

إنشاء وظائف مساعدة للتكامل مع Google APIs

التحقق من reCAPTCHA

من الأفضل فصل استدعاءات الواجهات الخارجية داخل دوال أو ملفات مساعدة مستقلة، حتى تبقى الشيفرة أوضح وأسهل للصيانة.

import requests
from django.conf import settings


def recaptcha_validation(token):
    result = requests.post(
        'https://www.google.com/recaptcha/api/siteverify',
        data={
            'secret': settings.RECAPTCHA_PRIVATE_KEY,
            'response': token,
        }
    )
    return result.json()

إنشاء دالة لحساب المسارات

يمكن كذلك بناء دالة تتعامل مع Directions API وتعيد بيانات المسافة والمدة وخطوات المسار في شكل مناسب للعرض.

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

بناء العروض Views ومعالجة النماذج

تسجيل المستخدم الجديد

عند إرسال نموذج التسجيل:

1. يُلتقط رمز token من reCAPTCHA.
2. يُرسل إلى الخادم للتحقق منه.
3. إذا كانت النتيجة ناجحة، يُنشأ المستخدم.
4. يُحفَظ البريد الإلكتروني داخل حقل username.
5. تُخزن درجة captcha score في ملف المستخدم.
6. يتم تسجيل دخوله مباشرة.

هذا التسلسل يمنح التطبيق أمانًا أفضل دون التأثير على تجربة الاستخدام.

تحديث العنوان باستخدام Google Places API

بعد تسجيل الدخول، يمكن للمستخدم إضافة عنوانه. أثناء الكتابة في حقل العنوان، يقترح Google عناوين مطابقة. وعند اختيار العنوان المناسب، يتم تلقائيًا:

• تعبئة العنوان الكامل.
• استخراج المدينة والمنطقة والرمز البريدي.
• إضافة الدولة.
• تحديد longitude وlatitude.

ثم يرسل النموذج عبر Ajax لتحديث الملف الشخصي دون إعادة تحميل الصفحة كاملة.

بناء الواجهة الأمامية باستخدام HTML وJavaScript

القالب الأساسي base.html

في المشاريع المنظمة، يفضل إنشاء قالب أساسي يحتوي على:

• ملف CSS الرئيسي.
• مكتبة jQuery.
• مكتبة التنبيهات مثل Toastr.
• أقسام قابلة للتمديد باستخدام كتل {% block %}.

بهذا الأسلوب، ترث الصفحات مثل التسجيل، تسجيل الدخول، الملف الشخصي، والخريطة نفس الهيكل العام.

استخدام Ajax لتحسين تجربة المستخدم

بدل إرسال النماذج بالطريقة التقليدية، يستفيد التطبيق من Ajax لتنفيذ الإرسال في الخلفية. النتيجة:

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

كما يمكن استخدام دوال مساعدة لتبديل حالة الأزرار أثناء الإرسال، مثل إظهار مؤشر تحميل ثم إعادة النص الأصلي للزر بعد اكتمال العملية.

دمج Google Places API مع حقل العنوان

عند تحميل الصفحة الخاصة بالملف الشخصي، يتم استدعاء مكتبة الخرائط بهذا الشكل:

$.getScript('https://maps.googleapis.com/maps/api/js?key=' + googleApiKey + '&libraries=places', function () {
    google.maps.event.addDomListener(window, 'load', initAutocomplete);
});

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

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

إنشاء مسار بين عدة نقاط باستخدام Google Maps

كيف يعمل نموذج المسارات؟

يوفر التطبيق نموذجًا يتيح إدخال:

• نقطة البداية.
• نقطة توقف أولى.
• نقطة توقف ثانية.
• الوجهة النهائية.

كل حقل يستفيد من Places Autocomplete أيضًا. وبعد اكتمال جميع الحقول، تُجمع الإحداثيات في سلسلة معاملات query string، ثم يُعاد توجيه المستخدم إلى صفحة الخريطة.

عرض الخريطة والاتجاهات

في صفحة الخريطة، تُقرأ القيم من الرابط ثم تُمرر إلى Directions API. إذا كانت البيانات مكتملة وصحيحة، تظهر النتيجة على شكل:

• الخريطة المرئية.
• المسافة الكلية.
• المدة الزمنية التقديرية.
• خطوات التنقل بالتفصيل.

يمكن كذلك إظهار أو إخفاء التعليمات التفصيلية عبر زر أو رابط تفاعلي باستخدام JavaScript.

اختبار المشروع وتشغيله محليًا

تثبيت الحزم الإضافية وإنشاء قاعدة البيانات

قبل تشغيل الخادم المحلي، قد تحتاج إلى تثبيت حزم إضافية يعتمد عليها المشروع، مثل requests أو humanfriendly إن كانت مستخدمة ضمن تنسيق المدة الزمنية.

pip install requests
pip install humanfriendly
python manage.py makemigrations
python manage.py migrate
python manage.py runserver

ماذا تختبر بعد التشغيل؟

1. انتقال الزائر غير المسجل إلى صفحة تسجيل الدخول تلقائيًا.
2. عمل نموذج التسجيل وربطه مع reCAPTCHA v3.
3. إنشاء المستخدم وتسجيل دخوله.
4. إمكانية إضافة العنوان عبر Places API.
5. حفظ الإحداثيات والبيانات الجغرافية داخل الملف الشخصي.
6. إدخال 4 نقاط وإنشاء مسار ناجح بينها.
7. ظهور الخريطة وخطوات الاتجاهات بشكل صحيح.

أفضل ممارسات لتحسين المشروع قبل النشر

حماية المفاتيح السرية

لا تترك قيم API Key وSecret Key داخل المستودع البرمجي. استخدم متغيرات البيئة، وفعّل قيود الاستخدام من لوحة Google Cloud.

فصل البيئات

اجعل إعدادات التطوير مختلفة عن الإنتاج. على سبيل المثال، يمكن استخدام ملف إعدادات مستقل أو نظام تحميل ديناميكي للإعدادات حسب البيئة.

تقييد المفاتيح والفوترة

بعض خدمات Google Maps Platform تتطلب تفعيل الفوترة. كما يجب تقييد المفاتيح حسب النطاقات أو التطبيقات المسموح لها باستخدامها حتى لا تتعرض لاستهلاك غير متوقع.

تحسين تجربة المستخدم

• أضف رسائل خطأ واضحة عند فشل جلب العنوان أو المسار.
• وفّر حالة تحميل مرئية أثناء انتظار رد API.
• عالج الحالات الناقصة مثل عدم اكتمال جميع نقاط المسار.

لماذا هذا النوع من المشاريع مفيد في السيو وAdSense؟

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

• يعالج مشكلة واضحة.
• يشرح خطوات التنفيذ بتسلسل منطقي.
• يعرض أمثلة واقعية قابلة للتطوير.
• يتجنب النسخ الحرفي والحشو.

ومن منظور جودة المحتوى، فإن المقالات التي تقدم فهمًا حقيقيًا بدل تلخيص سطحي تكون أفضل من حيث تجربة المستخدم، وتنسجم أكثر مع معايير القبول في Google AdSense.

الخلاصة التقنية

دمج Google APIs مع Python وDjango ليس مجرد إضافة خدمة خارجية، بل هو بناء طبقة ذكية تجمع بين الأمان، البيانات الجغرافية، والتفاعل اللحظي داخل التطبيق. أفضل نهج هنا هو توزيع المسؤوليات بوضوح: Django يدير المنطق والخادم، وJavaScript يتولى التفاعل المباشر مع الخرائط والعناوين، بينما تقوم واجهات Google بتوفير البيانات والخدمات الدقيقة. هذا النمط من البناء مناسب جدًا للتطبيقات الخدمية واللوجستية وتطبيقات الحجز والتوصيل، ويمكن تطويره لاحقًا ليشمل تتبعًا مباشرًا، حساب تكاليف، أو تحسينًا متقدمًا للمسارات.