إعداد Weather API

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

لبدء استخدام Weather API، يمكنك إما طلب مفتاح تجريبي لـ "خرائط Google" أو إعداد حساب وتفعيل الفوترة.

الحصول على مفتاح Maps Demo Key

‫Maps Demo Key هي ميزة مجانية تتيح لك البدء بإنشاء نماذج أولية باستخدام Weather API بدون إدخال معلومات الفوترة. إنّ مفتاح Maps Demo Key مخصّص لأغراض الاختبار وإنشاء النماذج الأوّلية فقط، وليس مصمّمًا للاستخدام في بيئة إنتاجية. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الحصول على مفتاح Maps Demo Key واستخدامه مع Weather API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

وحدة التحكّم

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

   تفعيل Weather API

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

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

gcloud

gcloud services enable \
    --project "PROJECT" \
    "weather.googleapis.com"

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

• gcloud services enable
• gcloud services disable

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

نقطة رئيسية: يتضمّن دليل الإعداد هذا إجراءات ضبط مفتاح واجهة برمجة التطبيقات وإنشاء رمز OAuth المميّز. اختَر الإجراء المناسب لبيئة النشر.

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

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

وحدة التحكّم

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

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

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

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

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

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

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

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

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

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

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

gcloud

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

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

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=weather.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=weather.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".

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

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

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

   curl -X GET "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"
   

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

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

{
  "currentTime": "2025-07-01T12:33:24.606422609Z",
  "timeZone": {
    "id": "America/Los_Angeles"
  },
  "isDaytime": false,
  "weatherCondition": {
    "iconBaseUri": "https://maps.gstatic.com/weather/v1/partly_clear",
    "description": {
      "text": "Partly cloudy",
      "languageCode": "en"
    },
    "type": "PARTLY_CLOUDY"
  },
  "temperature": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "feelsLikeTemperature": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "dewPoint": {
    "degrees": 12,
    "unit": "CELSIUS"
  },
  "heatIndex": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "windChill": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "relativeHumidity": 78,
  "uvIndex": 0,
  "precipitation": {
    "probability": {
      "percent": 3,
      "type": "RAIN"
    },
    "snowQpf": {
      "quantity": 0,
      "unit": "MILLIMETERS"
    },
    "qpf": {
      "quantity": 0,
      "unit": "MILLIMETERS"
    }
  },
  "thunderstormProbability": 0,
  "airPressure": {
    "meanSeaLevelMillibars": 1011.5
  },
  ...
}

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

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

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

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

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

إنشاء رمز OAuth مميّز

تتيح واجهة Weather API استخدام بروتوكول OAuth 2.0 للمصادقة. تتيح Google سيناريوهات OAuth 2.0 الشائعة، مثل سيناريوهات خادم الويب.

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

نظرة عامة على OAuth

يمكنك إنشاء رموز الدخول وإدارتها باستخدام OAuth بعدة طرق حسب بيئة النشر.

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

بدلاً من ذلك، يمكنك دمج Weather API في تطبيق متوافق مع Android أو iOS. لمزيد من المعلومات حول استخدام OAuth وإدارة رموز الدخول لبيئات النشر المختلفة، يُرجى الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.

نطاقات OAuth

لاستخدام OAuth مع Weather API، عليك منح رمز OAuth المميّز النطاق التالي:

https://www.googleapis.com/auth/cloud-platform

مثال: تجربة طلبات بيانات من واجهة برمجة التطبيقات REST API في بيئة التطوير المحلية

إذا لم تكن لديك بيئة تنشئ رموزًا مميّزة وأردت تجربة Weather API باستخدام رمز OAuth مميّز، اتّبِع الإجراءات الواردة في هذا القسم.

يوضّح هذا المثال كيفية استخدام رمز OAuth المميّز الذي توفّره بيانات الاعتماد التلقائية للتطبيق (ADC) لإجراء الطلب. لمزيد من المعلومات حول استخدام ADC لطلب Google APIs من خلال مكتبات العملاء، يُرجى الاطّلاع على المصادقة باستخدام مكتبات العملاء.

استخدِم إجراء REST التالي لأغراض التطوير أو الاختبار فقط، وليس لأغراض الإنتاج.

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

قبل إجراء طلب REST باستخدام ADC، استخدِم واجهة سطر الأوامر (CLI) في gcloud لتقديم بيانات الاعتماد إلى ADC:

1. ثبِّت واجهة سطر الأوامر (CLI) في gcloud وافتحها. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تثبيت gcloud CLI.

2. المصادقة باستخدام واجهة سطر الأوامر (CLI) في gcloud:

   gcloud auth application-default login

3. أكمِل عملية تسجيل الدخول لحفظ بيانات الاعتماد في ملف بيانات الاعتماد المحلي الذي تستخدمه ADC.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد ADC لبيئة تطوير محلية.

إرسال طلب REST

في هذا المثال، يتم تمرير عنوانَي طلب:

• مرِّر رمز OAuth المميّز في العنوان Authorization باستخدام الأمر التالي لإنشاء الرمز المميّز:

  gcloud auth application-default print-access-token

  يحتوي الرمز المميّز الذي تم إرجاعه على نطاق https://www.googleapis.com/auth/cloud-platform.

• أدخِل رقم تعريف أو اسم مشروعك على Google Cloud الذي تم تفعيل الفوترة فيه في العنوان X-Goog-User-Project.

لطلب Weather API باستخدام رمز OAuth المميّز، أكمِل الخطوات التالية:

1. في عينة التعليمات البرمجية التالية، استبدِل PROJECT_NUMBER_OR_ID برقم مشروعك على Google Cloud أو رقم تعريفه:

   curl -X GET \
   -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://weather.googleapis.com/v1/currentConditions:lookup?location.latitude=37.4220&location.longitude=-122.0841"

2. لنسخ الأمر curl، انقر على نسخ في عينة التعليمات البرمجية.

3. الصِق الأمر في نافذة المحطة الطرفية، ثم شغِّله.

الردّ هو عنصر JSON:

{
  "currentTime": "2025-07-01T12:33:24.606422609Z",
  "timeZone": {
    "id": "America/Los_Angeles"
  },
  "isDaytime": false,
  "weatherCondition": {
    "iconBaseUri": "https://maps.gstatic.com/weather/v1/partly_clear",
    "description": {
      "text": "Partly cloudy",
      "languageCode": "en"
    },
    "type": "PARTLY_CLOUDY"
  },
  "temperature": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "feelsLikeTemperature": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "dewPoint": {
    "degrees": 12,
    "unit": "CELSIUS"
  },
  "heatIndex": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "windChill": {
    "degrees": 16,
    "unit": "CELSIUS"
  },
  "relativeHumidity": 78,
  "uvIndex": 0,
  "precipitation": {
    "probability": {
      "percent": 3,
      "type": "RAIN"
    },
    "snowQpf": {
      "quantity": 0,
      "unit": "MILLIMETERS"
    },
    "qpf": {
      "quantity": 0,
      "unit": "MILLIMETERS"
    }
  },
  "thunderstormProbability": 0,
  "airPressure": {
    "meanSeaLevelMillibars": 1011.5
  },
  ...
}

تحديد المشاكل وحلّها

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

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

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