إعداد Time Zone API

يوضِّح هذا المستند الخطوات التي يجب اتّباعها لبدء استخدام Time Zone API.

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

يساعدك هذا الإجراء في إعداد حساب على Google Cloud ومشروع على السحابة الإلكترونية مع تفعيل الفوترة. يجب أيضًا أن تكون على دراية بكيفية تحصيل الرسوم منك مقابل استخدام Time Zone API.

1. راجِع الفوترة وتكلفة الاستخدام في استخدام Time Zone API والفوترة.

2. تأكَّد من أنّ لديك حساب على Google Cloud.

   سجِّل الدخول إلى Google Cloud Console
   ملاحظة: إذا كنت مستخدمًا جديدًا وليس لديك حساب على Google Cloud، ما يعني أنّه لا يمكنك تسجيل الدخول إلى وحدة التحكّم، يُرجى الاطّلاع على بدء استخدام "منصة خرائط Google".

3. تأكَّد من أنّ لديك مشروعًا على Google Cloud تم تفعيل الفوترة فيه.

   انتقِل إلى صفحة "الفوترة"
   ملاحظة: إذا كنت مستخدمًا جديدًا وليس لديك مشروع على Google Cloud، يُرجى الاطّلاع على بدء استخدام "منصة خرائط Google".
1. اختَر مشروعك لفتح صفحة الفوترة.

2. في صفحة الفوترة:

   • إذا كانت الفوترة مفعَّلة للمشروع المحدّد، وكان لديك حساب فوترة واحد فقط، ستفتح صفحة الفوترة.
   • إذا كانت لديك حسابات فوترة متعددة، اختَر الانتقال إلى حساب الفوترة المرتبط للاطّلاع على تفاصيل حساب الفوترة المرتبط بالمشروع.
   • إذا كان هناك حساب فوترة ولكنّه غير مرتبط بالمشروع، سيُطلب منك ربط حساب فوترة بالمشروع.
   • إذا لم يكن هناك حساب فوترة، أو إذا أردت إنشاء حساب فوترة جديد، اختَر إدارة حسابات الفوترة لإنشاء حساب فوترة جديد. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء حساب فوترة جديد للخدمة الذاتية على Google Cloud.

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

قبل استخدام Time Zone API، يجب استخدام وحدة تحكّم Google Cloud أو الأمر gcloud لتفعيلها في مشروعك على Google Cloud.

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

لتفعيل واجهة برمجة التطبيقات:

وحدة التحكّم

1. افتح صفحة المنتج في Google Cloud Console:

   تفعيل Time Zone API

2. يمكنك النقر على الزر تمكين.

   ملاحظة: إذا كانت واجهة برمجة التطبيقات مفعَّلة، سيظهر لك الزر إدارة بدلاً من تفعيل.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "timezone-backend.googleapis.com"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:

• gcloud services enable
• gcloud services disable

الحصول على مفتاح واجهة برمجة تطبيقات لاستخدامه مع Time Zone API

تتم حماية منتجات "منصة خرائط Google" من الاستخدام غير المصرَّح به من خلال طلب تضمين مفتاح واجهة برمجة التطبيقات في طلبات البيانات من واجهة برمجة التطبيقات.

مفتاح واجهة برمجة التطبيقات هو سلسلة فريدة من الأحرف الأبجدية الرقمية تربط حسابك على Cloud Billing ومشروعك على Google Cloud بالطلب الذي يرسله تطبيقك إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) على "منصة خرائط Google". لإنشاء مفتاح جديد أو إضافة واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) إلى مفتاح حالي، اتّبِع التعليمات التالية.

وحدة التحكّم

1. انتقِل إلى صفحة منصة خرائط Google > المفاتيح وبيانات الاعتماد.

   الانتقال إلى صفحة "المفاتيح وبيانات الاعتماد"

2. اختَر مشروعك إذا طُلب منك ذلك.

3. نفّذ أيًا مما يلي:

   • إنشاء مفتاح جديد:

     1. انقر على إنشاء بيانات الاعتماد > مفتاح واجهة برمجة التطبيقات.
     2. في لوحة إنشاء مفتاح واجهة برمجة التطبيقات، افتح قائمة اختيار قيود واجهة برمجة التطبيقات.
     3. امسح أي واجهات برمجة تطبيقات لا يحتاجها هذا المفتاح، وتأكَّد من بقاء Time Zone API محدَّدة.
     4. انقر على إنشاء. تعرض اللوحة مفتاح واجهة برمجة التطبيقات الجديد.

   • استخدام مفتاح حالي:

     1. انقر على اسم المفتاح.
     2. في قائمة اختيار قيود واجهة برمجة التطبيقات، اختَر Time Zone API.
     3. انقر على حفظ.

   لا يؤدي اختيار واجهة برمجة تطبيقات هنا إلى تفعيلها. تأكَّد من تفعيل Time Zone API في صفحة مكتبة واجهة برمجة التطبيقات.

4. للاطّلاع على سلسلة المفاتيح لاحقًا، انتقِل إلى صفحة المفاتيح وبيانات الاعتماد وانقر على عرض المفتاح للمفتاح المطلوب.

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

gcloud

استبدِل PROJECT_ID برقم تعريف مشروعك في الأوامر التالية.

• إنشاء مفتاح جديد: نفِّذ الأمر التالي، واستبدِل DISPLAY_NAME باسم المفتاح.

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=timezone-backend.googleapis.com

  يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:

  • gcloud services api-keys create

• استخدام مفتاح حالي: نفِّذ الأمر التالي، واستبدِل KEY_ID بمعرّف المفتاح. تحتفظ العلامة --append بواجهات برمجة التطبيقات التي يسمح بها المفتاح حاليًا. وبدونها، يستبدلها الأمر.

  gcloud services api-keys update KEY_ID \
      --project="PROJECT_ID" \
      --append \
      --api-target=service=timezone-backend.googleapis.com

  يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:

  • gcloud services api-keys update
  • gcloud services api-keys list

  معرّف المفتاح ليس سلسلة المفتاح أو اسم العرض. للعثور عليه، شغِّل gcloud services api-keys list --project="PROJECT_ID". رقم التعريف هو الجزء الأخير من حقل name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

للاطّلاع على سلسلة المفاتيح، شغِّل gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

إرسال طلب بيانات من واجهة برمجة التطبيقات

أرسِل طلب بيانات من واجهة برمجة التطبيقات إلى Time Zone API لعرض استجابة JSON تحتوي على معلومات المنطقة الزمنية لولاية نيفادا في الولايات المتحدة. تم ضبط الطابع الزمني على 5 ديسمبر 2024. يجب تضمين السلسلة الأبجدية الرقمية لمفتاح واجهة برمجة التطبيقات مع كل طلب واستخدام بروتوكول HTTPS للطلبات التي تتضمّن مفتاح واجهة برمجة التطبيقات.

1. انقر على API_KEY في الرمز أدناه لإدراج السلسلة الأبجدية الرقمية للمفتاح:

   curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'
   

2. انقر على رمز النسخ في عيّنة التعليمات البرمجية، ، لنسخ الأمر curl.
3. الصِق الأمر في نافذة الوحدة الطرفية ونفِّذه.

الردّ هو عنصر JSON بالصيغة التالية:

{
   "dstOffset" : 0,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Standard Time"
}

تطبيق قيود على مفتاح واجهة برمجة التطبيقات

تنبيه: يمكن استخدام مفتاح واجهة برمجة تطبيقات غير مقيّد لإرسال طلب إلى أي خدمة في "منصة خرائط Google"، بما في ذلك Time Zone API. أنت مسؤول ماليًا عن الرسوم الناتجة عن إساءة استخدام مفاتيح واجهة برمجة التطبيقات غير المقيَّدة.

تنصح Google بشدة بفرض قيود على مفاتيح واجهة برمجة التطبيقات من خلال حصر استخدامها على واجهات برمجة التطبيقات والتطبيقات التي تحتاج إليها فقط. يؤدي فرض قيود على مفاتيح واجهة برمجة التطبيقات إلى تعزيز أمان تطبيقك من خلال حمايته من الطلبات غير المبرَّرة. تتيح مفاتيح واجهة برمجة التطبيقات نوعَين من القيود:

• تحدّد القيود المفروضة على واجهة برمجة التطبيقات حِزم SDK وواجهات برمجة التطبيقات التي يمكن طلبها باستخدام مفتاح واجهة برمجة التطبيقات. تتطلّب وحدة التحكّم وgcloud CLI فرض قيد واحد على الأقل على واجهة برمجة التطبيقات عند إنشاء مفتاح.
• تحدّد قيود التطبيقات المواقع الإلكترونية أو عناوين IP أو التطبيقات التي يمكنها استخدام مفتاح واجهة برمجة التطبيقات.

لمزيد من المعلومات حول تطبيق القيود، يُرجى الاطّلاع على مقالة فرض قيود على مفاتيح واجهة برمجة التطبيقات.

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

بعد تفعيل Time Zone API وإرسال طلب ناجح، يمكنك الاطّلاع على طلبات Time Zone API والردود عليها لمزيد من المعلومات حول استخدام واجهة برمجة التطبيقات.