اولین فراخوانی API گوگل هلث خود را با استفاده از OAuth2 Playground انجام دهید

۱. مقدمه

OAuth 2.0 Playground ابزاری مبتنی بر وب است که به شما کمک می‌کند جریان‌های Google OAuth 2.0 را بدون نوشتن هیچ کدی آزمایش کنید. این آزمایشگاه کد به شما نشان می‌دهد که چگونه پروژه Google Cloud خود را راه‌اندازی کنید، اعتبارنامه‌ها را دریافت کنید، جریان مجوز را با OAuth 2.0 Playground آغاز کنید و اولین تماس خود را با یکی از نقاط پایانی API Google Health برقرار کنید.

آنچه یاد خواهید گرفت

  • نحوه تنظیم شناسه کلاینت در کنسول گوگل کلود.
  • چگونه با استفاده از OAuth 2.0 Playground، جریان مجوزدهی Google OAuth 2.0 را برای دریافت توکن دسترسی و توکن به‌روزرسانی طی کنیم.
  • نحوه برقراری تماس با نقاط پایانی API گوگل هلث با استفاده از OAuth 2.0 Playground.

آنچه نیاز دارید

برای تنظیم برنامه موبایل Fitbit:

  1. در فروشگاه اپل یا فروشگاه گوگل پلی، برنامه موبایل Fitbit را جستجو کرده و آن را دانلود کنید.
  2. آیکون برنامه را انتخاب کنید.
  3. روی ورود با گوگل کلیک کنید.
  4. حساب گوگل خود را انتخاب کنید و دکمه ادامه را فشار دهید.

۲. راه‌اندازی پروژه گوگل کلود

شما از کنسول Google Cloud برای ایجاد یک شناسه کلاینت و فعال کردن استفاده از API Google Health استفاده خواهید کرد.

  1. وارد کنسول گوگل کلود شوید.
  2. برای ایجاد یک پروژه جدید:
    1. روی «انتخاب پروژه» از انتخابگر پروژه کلیک کنید.
    2. در گوشه بالا سمت راست، گزینه «پروژه جدید» را انتخاب کنید.
    3. نام پروژه خود را وارد کنید.
    4. موقعیت مکانی خود را وارد کنید (برای مثال، "بدون سازمان").
    5. روی دکمه‌ی ایجاد کلیک کنید.
    6. پروژه خود را انتخاب کنید.

فعال کردن API سلامت گوگل

  1. در گوشه بالا سمت چپ، روی نماد منو کلیک کنید:منو
  2. APIها و خدمات > کتابخانه را انتخاب کنید.
  3. عبارت «Google Health API» را جستجو کنید و آن را فعال کنید.

اعتبارنامه‌های OAuth خود را تنظیم کنید

اگر در کنسول گوگل کلود نیستید، به کنسول گوگل کلود بروید.

  1. در گوشه بالا سمت چپ، روی نماد منو کلیک کنید:منو
  2. APIها و خدمات > اعتبارنامه‌ها را انتخاب کنید.
  3. در قسمت بالا و وسط، + ایجاد اعتبارنامه‌ها > شناسه کلاینت OAuth را انتخاب کنید.
  4. روی دکمه‌ی «پیکربندی صفحه‌ی رضایت » کلیک کنید. اگر پیام «پلتفرم تأیید هویت گوگل هنوز پیکربندی نشده است» ظاهر شد، روی دکمه‌ی «شروع به کار » کلیک کنید.
  5. در بخش ۱:
    1. نام برنامه را وارد کنید.
    2. ایمیل پشتیبانی کاربر را وارد کنید.
    3. روی دکمه‌ی بعدی کلیک کنید.
  6. در بخش ۲:
    1. خارجی را انتخاب کنید.
    2. روی دکمه‌ی بعدی کلیک کنید.
  7. در بخش ۳:
    1. در قسمت اطلاعات تماس، آدرس ایمیل خود را وارد کنید.
    2. روی دکمه‌ی بعدی کلیک کنید.
  8. در بخش ۴:
    1. برای موافقت با خط‌مشی داده‌های کاربر سرویس‌های API گوگل، روی کادر تأیید کلیک کنید.
    2. روی دکمه‌ی ایجاد کلیک کنید.
  9. به APIها و خدمات > اعتبارنامه‌ها بروید و + ایجاد اعتبارنامه‌ها > شناسه کلاینت OAuth را انتخاب کنید.
  10. نوع برنامه را Web Application انتخاب کنید.
  11. نام شناسه مشتری را وارد کنید.
  12. قسمت Authorized JavaScript origins را خالی بگذارید.
  13. در زیر Authorized redirect URIs ، روی + Add URI کلیک کنید و URI های زیر را اضافه کنید:
    • https://www.google.com
    • https://developers.google.com/oauthplayground
  14. روی دکمه‌ی ایجاد کلیک کنید.
  15. کنسول گوگل پیامی مبنی بر ایجاد شناسه کلاینت شما نشان می‌دهد. یا روی لینک دانلود JSON کلیک کنید تا شناسه کلاینت و رمز کلاینت دانلود شوند، یا مقادیر را یادداشت کنید. پس از آن نمی‌توانید رمز کلاینت خود را بازیابی کنید.
  16. روی تأیید کلیک کنید. به صفحه «شناسه‌های کلاینت OAuth 2.0» باز خواهید گشت.
  17. شناسه کلاینت شما به پروژه‌تان اضافه خواهد شد. برای مشاهده جزئیات، روی آدرس URL شناسه کلاینت کلیک کنید.

افزودن کاربران آزمایشی

  1. در پنل سمت چپ، گزینه‌ی «مخاطب» (Audience) را انتخاب کنید. باید ببینید که «وضعیت انتشار» (Publishing status) روی «در حال آزمایش» (Testing) و «نوع کاربر» (User type) روی «خارجی» (External) تنظیم شده است.
  2. در بخش «کاربران آزمایشی»، روی دکمه + افزودن کاربران کلیک کنید. آدرس ایمیل هر کاربری را که می‌خواهید اطلاعاتش را بازیابی کنید، وارد کنید.
  3. روی دکمه ذخیره کلیک کنید.

افزودن محدوده‌ها به شناسه کلاینت

  1. در پنل سمت چپ، گزینه دسترسی به داده‌ها (Data Access) را انتخاب کنید.
  2. روی دکمه‌ی افزودن یا حذف محدوده‌ها کلیک کنید.
  3. در ستون API، عبارت "Google Health API" را جستجو کنید. برای این آزمایشگاه کد، ما از محدوده .../auth/googlehealth.activity_and_fitness.readonly استفاده می‌کنیم.
  4. پس از انتخاب محدوده، دکمه به‌روزرسانی را فشار دهید تا به صفحه دسترسی به داده‌ها بازگردید.
  5. روی دکمه ذخیره کلیک کنید.

شما تنظیم شناسه کلاینت خود را به پایان رسانده‌اید.

۳. اضافه کردن داده‌ها به برنامه موبایل Fitbit

برای کاربران جدید Fitbit، ممکن است در حساب Fitbit خود داده‌ای برای جستجو نداشته باشید. ما قصد داریم به صورت دستی یک گزارش تمرین اضافه کنیم که می‌توانیم از طریق یکی از نقاط پایانی آن را جستجو کنیم. برای ثبت دستی یک تمرین، این مراحل را دنبال کنید:

  1. برنامه موبایل Fitbit را در دستگاه خود باز کنید. در صورت نیاز، وارد حساب Fitbit خود شوید.
  2. در گوشه پایین سمت راست صفحه، روی دکمه + ضربه بزنید.
  3. در بخش «ثبت دستی»، روی «فعالیت» ضربه بزنید
  4. نوع ورزش Walk (پیاده‌روی) را جستجو کرده و آن را انتخاب کنید.
  5. زمان شروع امروز را وارد کنید.
  6. مدت زمان را به ۱۵ دقیقه تغییر دهید.
  7. فاصله را ۱.۰ مایل (۱.۰ کیلومتر) در نظر بگیرید.
  8. روی افزودن ضربه بزنید.
  9. با نگه داشتن انگشت روی صفحه و کشیدن آن به پایین، برنامه تلفن همراه را با سرورهای Fitbit همگام‌سازی کنید. وقتی انگشت خود را بردارید، باید همگام‌سازی برنامه تلفن همراه را ببینید.
  10. در بخش «فعالیت»، باید ورودی پیاده‌روی ثبت‌شده‌ی دستی خود را ببینید. تصویر صفحه نمایش، فعالیت پیاده‌روی را نشان می‌دهد.

۴. احراز هویت در OAuth 2.0 Playground

به OAuth 2.0 Playground بروید.

رابط برنامه‌نویسی کاربردی گوگل هلث (Google Health API) ایجاب می‌کند که شما از اعتبارنامه‌های OAuth خودتان برای Playground استفاده کنید.

  1. روی نماد چرخ دنده پیکربندی OAuth 2.0 در بالا سمت راست کلیک کنید.
  2. استفاده از اعتبارنامه‌های OAuth خودتان را انتخاب کنید.
  3. شناسه کلاینت OAuth و رمز کلاینت OAuth که در طول راه‌اندازی پروژه Google Cloud به دست آورده‌اید را وارد کنید.

رابط کاربری Playground به سه مرحله اصلی تقسیم می‌شود که ما آنها را دنبال خواهیم کرد:

  1. انتخاب و تأیید APIها
  2. کد مجوز تبادل برای توکن‌ها
  3. ارسال درخواست به API

انتخاب و تأیید APIها

اینجاست که محدوده‌های API مورد نظر برای درخواست را انتخاب می‌کنید.

  1. در مرحله ۱ ، Google Health API نسخه ۴ را در فهرست APIها پیدا کنید و آن را باز کنید.
  2. گزینه https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly را انتخاب کنید. اگر محدوده مورد نیاز شما در لیست نمایش داده نمی‌شود، می‌توانید آن را به صورت دستی در فیلد «محدوده‌های خودتان را وارد کنید» وارد کنید.
  3. روی تأیید APIها کلیک کنید.
  4. درخواستی به نقطه پایانی مجوز OAuth 2.0 گوگل ارسال می‌شود، محدوده‌های انتخاب‌شده در درخواست گنجانده می‌شوند و سپس به صفحه رضایت حساب گوگل هدایت می‌شوید.
  5. با یک حساب کاربری آزمایشی که در بخش راه‌اندازی پروژه Google Cloud پیکربندی کرده‌اید، وارد شوید (اگر قبلاً وارد سیستم نشده‌اید).
  6. مجوزهای درخواستی را بررسی کنید و برای اعطای دسترسی، روی ادامه کلیک کنید.

وقتی رضایت می‌دهید، گوگل شما را به Playground هدایت می‌کند و یک کد مجوز به ابزار ارائه می‌دهد که در مرحله بعدی استفاده می‌شود.

پنل درخواست/پاسخ در سمت راست، جریان کامل تغییر مسیر HTTP را نمایش می‌دهد.

پاسخ درخواست مجوز اولیه، یک ریدایرکت 302 Found است:

HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground&prompt=consent&response_type=code&client_id=your_client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgooglehealth.activity_and_fitness.readonly&access_type=offline

درخواست حاصل که به Playground برگردانده می‌شود، حاوی کد مجوز است:

GET /oauthplayground/?iss=https://accounts.google.com&code=authorization_code&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly HTTP/1.1
Host: developers.google.com

کد مجوز، مقداری الفبایی-عددی است که توسط authorization_code بین code= و &scope در URL درخواست GET نمایش داده می‌شود. در این مثال، مقدار مشابه این است: 4/0AbPOj...

کد مجوز تبادل برای توکن‌ها

در این مرحله، کد با توکن‌هایی مبادله می‌شود که به شما امکان می‌دهند درخواست‌های API ارسال کنید.

After completing Select & authorize APIs , the Playground automatically populates the authorization code field. To exchange it for tokens:

  1. در مرحله ۲، روی دکمه‌ی کد مجوز تبادل برای توکن‌ها کلیک کنید.
  2. access_token و refresh_token در پنل Request/Response در سمت راست ظاهر می‌شوند.

شما باید پاسخی مشابه زیر ببینید:

{
  "access_token": "ya29.a0AFH6S....",
  "refresh_token_expires_in": 604799,
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly",
  "refresh_token": "1/og..."
}

درباره توکن‌های به‌روزرسانی

وقتی کد مجوز را رد و بدل می‌کنید، پاسخ ممکن است علاوه بر access_token شامل refresh_token نیز باشد. access_token ها کوتاه‌مدت هستند (معمولاً ۱ ساعت). وقتی access_token منقضی می‌شود، باید از refresh_token برای دریافت access_token جدید بدون نیاز به ورود یا رضایت مجدد کاربر استفاده کنید. این امر به این دلیل امکان‌پذیر است که ما access_type=offline در درخواست مجوز خود گنجانده‌ایم.

اگر در پاسخ، refresh_token دریافت نکردید، ممکن است به این دلیل باشد که قبلاً برای این برنامه و محدوده‌ها رضایت داده‌اید. توکن‌های Refresh معمولاً فقط اولین باری که کاربر برای برنامه شما رضایت می‌دهد، یا زمانی که prompt=consent به URL مجوز اضافه می‌شود تا صفحه رضایت را حتی در مجوزهای بعدی نیز نمایش دهد، صادر می‌شوند.

refresh_token اعتبار بالایی دارد، اما اگر به مدت ۶ ماه استفاده نشود، اگر کاربر دسترسی به برنامه شما را لغو کند یا به دلایل دیگر، ممکن است منقضی یا نامعتبر شود. شما باید refresh_token برای استفاده‌های بعدی به طور ایمن ذخیره کنید.

۵. ارسال درخواست به API

اکنون می‌توانید از توکن دسترسی خود برای ارسال درخواست به API گوگل هلث استفاده کنید. در مرحله ۳ در Playground، درخواست HTTP خود را با مشخص کردن Request URI ، HTTP Method ، هدرها و بدنه درخواست پیکربندی کنید.

  1. متد HTTP را روی GET تنظیم کنید.
  2. آدرس درخواست (Request URI) را روی https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints تنظیم کنید.
  3. روی ارسال درخواست کلیک کنید.

پاسخ باید شبیه به این باشد:

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/exercise/dataPoints/8896720705097069096",
      "dataSource": {
        "recordingMethod": "MANUAL",
        "platform": "FITBIT"
      },
      "exercise": {
        "interval": {
          "startTime": "2026-02-23T13:10:00Z",
          "startUtcOffset": "-18000s",
          "endTime": "2026-02-23T13:25:00Z",
          "endUtcOffset": "-18000s"
        },
        "exerciseType": "WALKING",
        "metricsSummary": {
          "caloriesKcal": 16,
          "distanceMillimiters": 1609344,
          "steps": "2038",
          "averagePaceSecondsPerMeter": 0.55923407301360051,
          "activeZoneMinutes": "0"
        },
        "exerciseMetadata": {},
        "displayName": "Walk",
        "activeDuration": "900s",
        "exerciseEvents": [
          {
            "eventTime": "2026-02-23T13:10:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "START"
          },
          {
            "eventTime": "2026-02-23T13:25:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "STOP"
          }
        ],
        "updateTime": "2026-02-24T01:19:22.450466Z"
      }
    },
    {
      "name": "users/2515055256096816351/dataTypes/exercise/dataPoints/5870930690409355408",
      "dataSource": {
        "recordingMethod": "MANUAL",
        "platform": "FITBIT"
      },
      "exercise": {
        "interval": {
          "startTime": "2026-02-23T06:00:00Z",
          "startUtcOffset": "-18000s",
          "endTime": "2026-02-23T06:15:00Z",
          "endUtcOffset": "-18000s"
        },
        "exerciseType": "WALKING",
        "metricsSummary": {
          "caloriesKcal": 17,
          "distanceMillimiters": 1609344,
          "steps": "2038",
          "averagePaceSecondsPerMeter": 0.55923407301360051,
          "averageHeartRateBeatsPerMinute": "81",
          "activeZoneMinutes": "0",
          "heartRateZoneDurations": {
            "lightTime": "900s"
          }
        },
        "exerciseMetadata": {},
        "displayName": "Walk",
        "activeDuration": "900s",
        "exerciseEvents": [
          {
            "eventTime": "2026-02-23T06:00:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "START"
          },
          {
            "eventTime": "2026-02-23T06:15:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "STOP"
          }
        ],
        "updateTime": "2026-02-23T08:29:39.480437Z"
      }
    }
  ],
  "nextPageToken": ""
}

بسیاری از نقاط پایانی از پارامترهای پرس‌وجو برای فیلتر کردن یا صفحه‌بندی پشتیبانی می‌کنند. برای مثال، برای فهرست کردن تمرین‌ها در یک محدوده زمانی خاص، درخواست URI را تغییر دهید تا شامل یک پارامتر فیلتر باشد:

https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints?filter=exercise.interval.civil_start_time >= "2026-02-22T00:00:00"

برای مشاهده نتایج فیلتر شده، دوباره روی ارسال درخواست کلیک کنید.

۶. تبریک

تبریک می‌گویم!

شما آزمایشگاه کد مقدماتی را به پایان رسانده‌اید و با موفقیت یاد گرفته‌اید که چگونه از OAuth2 Playground برای آزمایش احراز هویت OAuth 2.0 و برقراری تماس با نقاط پایانی API گوگل هلث استفاده کنید.

امیدواریم از ساخت برنامه‌هایی که با اکوسیستم Google Health API ادغام می‌شوند، لذت ببرید. برای اطلاعات بیشتر، سایر نقاط پایانی Google Health API را در مستندات مرجع بررسی کنید و درباره Google OAuth 2.0 برای برنامه‌های وب سرور بیشتر بدانید.