راه‌اندازی Weather API

این سند مراحلی را که باید برای شروع استفاده از Weather API انجام دهید شرح می‌دهد.

برای شروع استفاده از Weather API، می‌توانید «کلید نسخه نمایشی Maps» درخواست کنید یا حسابی راه‌اندازی کنید و صورت‌حساب را فعال کنید.

دریافت کردن «کلید نسخه نمایشی Maps»

«کلید نسخه نمایشی Maps» ویژگی‌ای رایگان است که به شما امکان می‌دهد بدون وارد کردن اطلاعات صورت‌حساب، نمونه‌سازی اولیه را با Weather API شروع کنید. «کلید نسخه نمایشی Maps» فقط برای اهداف آزمایشی و نمونه‌سازی درنظر گرفته شده است و برای استفاده در تولید طراحی نشده است. برای اطلاعات بیشتر، دریافت «کلید نسخه نمایشی Maps» و استفاده از آن با Weather API را ببینید.

دریافت کلید میانای برنامه‌سازی کاربردی استاندارد

وقتی آماده بودید کدتان را به تولید منتقل کنید، مراحل زیر را برای ایجاد کلید میانای برنامه‌سازی کاربردی و فعال کردن صورت‌حساب تکمیل کنید.

پیش‌نیازها

این رویه شما را در راه‌اندازی کردن «حساب Google Cloud» و پروژه Google Cloud با صورت‌حساب فعال راهنمایی می‌کند. همچنین باید با نحوه کسر هزینه برای استفاده از Weather API آشنا باشید.

  1. صورت‌حساب و هزینه استفاده را در استفاده و صورت‌حساب Weather API مرور کنید.

  2. تأیید کنید که حساب Google Cloud دارید.

    به سیستم کنسول Google Cloud وارد شوید

  3. تأیید کنید که پروژه Google Cloud با صورت‌حساب فعال دارید.

    رفتن به صفحه «صورت‌حساب»
    1. پروژه‌تان را انتخاب کنید تا صفحه صورت‌حساب باز شود.

    2. در صفحه صورت‌حساب:

      • اگر صورت‌حساب ازقبل برای پروژه انتخاب‌شده فعال شده باشد و فقط یک حساب صورت‌حساب داشته باشید، صفحه صورت‌حساب باز می‌شود.
      • اگر چند حساب صورت‌حساب دارید، رفتن به حساب صورت‌حساب پیوندشده را انتخاب کنید تا جزئیات مربوط به حساب صورت‌حساب مرتبط با پروژه را ببینید.
      • اگر حساب صورت‌حساب وجود داشته باشد اما با پروژه مرتبط نباشد، از شما خواسته می‌شود حساب صورت‌حساب را به پروژه پیوند دهید.
      • اگر حساب صورت‌حساب وجود ندارد، یا می‌خواهید حساب صورت‌حساب جدیدی ایجاد کنید، مدیریت حساب‌های صورت‌حساب را انتخاب کنید تا حساب صورت‌حساب جدیدی ایجاد کنید. برای اطلاعات بیشتر، ایجاد حساب Cloud Billing سلف سرویس جدید را ببینید.

فعال کردن میانای برنامه‌سازی کاربردی

قبل‌از اینکه بتوانید از Weather API استفاده کنید، باید از کنسول Google Cloud یا فرمان gcloud برای فعال کردن آن در پروژه Google Cloud خود استفاده کنید.

برای فعال کردن میانای برنامه‌سازی کاربردی:

کنسول

  1. صفحه محصول را در کنسول Google Cloud باز کنید:

    فعال کردن Weather API

  2. روی دکمه فعال کردن کلیک کنید.

gcloud

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

درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:

دریافت کلید میانای برنامه‌سازی کاربردی برای استفاده با Weather API

محصولات Google Maps Platform با الزام تماس‌های میانای برنامه‌سازی کاربردی به داشتن کلید میانای برنامه‌سازی کاربردی یا کد OAuth دربرابر استفاده غیرمجاز محافظت می‌شوند. رویه کلید میانای API در اولویت است. برای استفاده از کد OAuth به‌جای آن، ایجاد کد OAuth را ببینید.

کلید میانای برنامه‌سازی کاربردی رشته حرفی‌عددی منحصربه‌فردی است که حساب Cloud Billing و پروژه Google Cloud شما را با درخواستی که برنامه‌تان از میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار Google Maps Platform می‌کند مرتبط می‌کند. برای ایجاد کلید جدید یا افزودن میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار به کلید موجود، این دستورالعمل‌ها را دنبال کنید.

کنسول

  1. به صفحه پلاتفرم Google Maps > کلیدها و اطلاعات کاربری بروید.

    به صفحه «کلیدها و اعتبارنامه‌ها» بروید

  2. اگر درخواست شد، پروژه‌تان را انتخاب کنید.

  3. یکی از موارد زیر را انجام دهید:

    • ایجاد کلید جدید:

      1. روی ایجاد اطلاعات کاربری > کلید میانای API کلیک کنید.
      2. در پانل ایجاد کلید میانای API، فهرست انتخاب محدودیت‌های میانای API را باز کنید.
      3. هر API را که این کلید به آن نیاز ندارد پاک کنید و مطمئن شوید Weather API همچنان انتخاب شده باشد.
      4. روی ایجاد کردن کلیک کنید. پانل کلید میانای برنامه‌سازی کاربردی جدیدتان را نمایش می‌دهد.

    • استفاده از کلید موجود:

      1. روی نام کلید کلیک کنید.
      2. در فهرست انتخاب محدودیت‌های API، 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، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:

  • استفاده از کلید موجود: فرمان زیر را اجرا کنید و KEY_ID را با شناسه کلید جایگزین کنید. پرچم --append میاناهای برنامه‌سازی کاربردی را که کلید ازقبل مجاز کرده است حفظ می‌کند. بدون آن، فرمان جایگزین آن‌ها می‌شود.

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

    درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:

    شناسه کلید، رشته کلید یا نام نمایشی نیست. برای پیدا کردن آن، 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 برای اطلاعات شرایط فعلی در Mountain View، کالیفرنیا برگردانده شود. باید رشته الفبانمایی کلید میانای برنامه‌سازی کاربردی‌تان را در هر درخواست بگنجانید و برای درخواست‌هایی که شامل کلید میانای برنامه‌سازی کاربردی است از 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 اکیداً توصیه می‌کند که کلیدهای میانای API خود را با محدود کردن استفاده از آن‌ها فقط به میاناهای برنامه‌سازی کاربردی و برنامه‌هایی که به آن‌ها نیاز دارند، محدود کنید. محدود کردن کلیدهای میانای API با محافظت از برنامه شما دربرابر درخواست‌های غیرمجاز، امنیت آن را افزایش می‌دهد. کلیدهای میانای برنامه‌سازی کاربردی از دو نوع محدودیت پشتیبانی می‌کنند:

  • محدودیت‌های میانای API مشخص می‌کند کدام کیت‌های توسعه نرم‌افزار و میاناهای API را می‌توان بااستفاده از کلید میانای API فراخوانی کرد. کنسول و gcloud CLI هنگام ایجاد کلید به حداقل یک محدودیت API نیاز دارند.
  • محدودیت‌های برنامه مشخص می‌کند کدام وب‌سایت‌ها، نشانی‌های IP، یا برنامه‌ها می‌توانند از کلید میانای برنامه‌سازی کاربردی استفاده کنند.

برای اطلاعات بیشتر درباره اعمال محدودیت‌ها، به محدود کردن کلیدهای میانای برنامه‌سازی کاربردی مراجعه کنید.

ایجاد کد OAuth

Weather API از OAuth 2.0 برای اصالت‌سنجی پشتیبانی می‌کند. Google از سناریوهای رایج OAuth 2.0، مثل سناریوهای سرور وب، پشتیبانی می‌کند.

این سند نحوه ارسال کد OAuth به فراخوانی Weather API را در محیط توسعه نرم‌افزار شما شرح می‌دهد. برای اطلاعات بیشتر درباره استفاده از OAuth در محیط تولید، به روش‌های اصالت‌سنجی در Google مراجعه کنید.

نمای کلی OAuth

می‌توانید کد دسترسی را با OAuth به چند روش بسته به محیط استقرار خود ایجاد و مدیریت کنید.

می‌توانید از OAuth 2.0 برای تعاملات سروربه‌سرور بین برنامه‌تان و سرویس Google استفاده کنید. برای این سناریو، از حساب سرویسی استفاده می‌کنید که به‌جای کاربر فردی، با برنامه‌تان مرتبط است. می‌توانید بااستفاده از حساب سرویس و بدون دخالت مستقیم کاربران، درخواست‌های API ارسال کنید. برای اطلاعات بیشتر درباره روش‌های اصالت‌سنجی، به روش‌های اصالت‌سنجی در Google مراجعه کنید.

یا می‌توانید Weather API را در برنامه تلفن همراه Android یا iOS ادغام کنید. برای اطلاعات بیشتر درباره استفاده از OAuth و مدیریت کردن کد دسترسی برای محیط‌های استقرار مختلف، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.

دامنه‌های 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 ایجاد کنید، از gcloud CLI برای ارائه اعتبارنامه به ADC استفاده کنید:

  1. gcloud CLI را نصب و مقداردهی اولیه کنید. برای اطلاعات بیشتر، به نصب gcloud CLI مراجعه کنید.

  2. با gcloud CLI اصالت‌سنجی کنید:

    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
  },
  ...
}

عیب‌یابی

اگر درخواستتان پیام خطایی برمی‌گرداند که می‌گوید این میانای برنامه‌سازی کاربردی از اعتبارنامه کاربر نهایی پشتیبانی نمی‌کند، به عیب‌یابی راه‌اندازی ADC مراجعه کنید.

قدم بعدی چیست

اکنون که Weather API را فعال کرده‌اید و درخواست موفقی داشته‌اید، برای کسب اطلاعات بیشتر درباره استفاده از API، دریافت شرایط فعلی را ببینید.