۱. مقدمه
ویژوال استودیو کد (VS Code) و افزونه Rest Client ساخته شده توسط هواچائو مائو میتوانند به شما امکان دهند تا جریان رضایت Google OAuth و Google Health API را آزمایش کنید. این آزمایشگاه کد به شما نشان میدهد که چگونه افزونه Rest Client را راهاندازی کنید، چگونه جریان مجوز را آغاز کنید و اولین تماس خود را با یکی از نقاط پایانی Google Health API برقرار کنید. پس از آن، میتوانید مستندات Rest Client و مستندات Fitbit را برای ساخت سایر نقاط پایانی در پروژه HTTP خود مطالعه کنید.
اگر نمیخواهید از VS Code و Rest Client استفاده کنید، فراخوانیهای API را میتوان با دستورات curl انجام داد.
آنچه یاد خواهید گرفت
- نحوه تنظیم VS Code با افزونه Rest client.
- نحوه تنظیم شناسه کلاینت در کنسول گوگل کلود.
- چگونه از طریق فرآیند احراز هویت Google OAuth 2.0، توکن دسترسی و توکن رفرش دریافت کنیم.
- نحوه برقراری تماس با نقاط پایانی API گوگل هلث با استفاده از کلاینت Rest.
آنچه نیاز دارید
- اپلیکیشن موبایل فیتبیت
- ویژوال استودیو کد
- افزونه Rest Client توسط Huacho Mao.
برای تنظیم برنامه موبایل Fitbit:
- در فروشگاه اپل یا فروشگاه گوگل پلی، برنامه موبایل Fitbit را جستجو کرده و آن را دانلود کنید.
- آیکون برنامه را انتخاب کنید.
- روی ورود با گوگل کلیک کنید
- حساب گوگل خود را انتخاب کنید و دکمه ادامه را فشار دهید.
برای نصب ابزارهای ویژوال استودیو:
- دانلود VS Code. معمولاً فایل دانلودی حاوی فایل اجرایی است.
- کد VS را شروع کنید.
- افزونه Rest Client از Huachao Mao را نصب کنید.
- روی نماد افزونه کلیک کنید
در سمت چپ IDE. - عبارت REST Client ساختهی Huachao Mao را جستجو کنید و روی Install کلیک کنید.
- روی نماد افزونه کلیک کنید
۲. راهاندازی پروژه گوگل کلود
شما از کنسول Google Cloud برای ایجاد یک شناسه کلاینت و فعال کردن استفاده از API Google Health استفاده خواهید کرد.
- وارد کنسول گوگل کلود شوید.
- برای ایجاد یک پروژه جدید:
- روی «انتخاب پروژه» از انتخابگر پروژه کلیک کنید.
- در گوشه بالا سمت راست، گزینه «پروژه جدید» را انتخاب کنید.
- نام پروژه خود را وارد کنید.
- موقعیت مکانی خود را وارد کنید (برای مثال، "بدون سازمان").
- روی دکمهی ایجاد کلیک کنید.
- پروژه خود را انتخاب کنید.
فعال کردن API سلامت گوگل
- در گوشه بالا سمت چپ، روی نماد منو کلیک کنید:
- APIها و خدمات > کتابخانه را انتخاب کنید.
- عبارت «Google Health API» را جستجو کنید و آن را فعال کنید.
اعتبارنامههای OAuth خود را تنظیم کنید
اگر در کنسول گوگل کلود نیستید، به کنسول گوگل کلود بروید.
- در گوشه بالا سمت چپ، روی نماد منو کلیک کنید:
- APIها و خدمات > اعتبارنامهها را انتخاب کنید.
- در قسمت بالا و وسط، + ایجاد اعتبارنامهها > شناسه کلاینت OAuth را انتخاب کنید.
- روی دکمهی «پیکربندی صفحهی رضایت » کلیک کنید. اگر پیام «پلتفرم تأیید هویت گوگل هنوز پیکربندی نشده است» ظاهر شد، روی دکمهی «شروع به کار » کلیک کنید.
- در بخش ۱:
- نام برنامه را وارد کنید.
- ایمیل پشتیبانی کاربر را وارد کنید.
- روی دکمهی بعدی کلیک کنید.
- در بخش ۲:
- خارجی را انتخاب کنید.
- روی دکمهی بعدی کلیک کنید.
- در بخش ۳:
- در قسمت اطلاعات تماس، آدرس ایمیل خود را وارد کنید.
- روی دکمهی بعدی کلیک کنید.
- در بخش ۴:
- برای موافقت با خطمشی دادههای کاربر سرویسهای API گوگل، روی کادر تأیید کلیک کنید.
- روی دکمهی ایجاد کلیک کنید.
- در بخش معیارها، دکمهی «ایجاد کلاینت OAuth» را فشار دهید.
- نوع برنامه را Web Application انتخاب کنید.
- نام شناسه مشتری را وارد کنید.
- قسمت Authorized JavaScript origins را خالی بگذارید.
- در زیر Authorized redirect URIs ، دکمه + Add URI را فشار دهید. عبارت "https://www.google.com" را به عنوان URL ریدایرکت خود وارد کنید.
- روی دکمهی ایجاد کلیک کنید.
- کنسول گوگل پیامی مبنی بر ایجاد شناسه کلاینت شما نشان میدهد. یا روی لینک دانلود JSON کلیک کنید تا شناسه کلاینت و رمز کلاینت دانلود شوند، یا مقادیر را یادداشت کنید. پس از آن نمیتوانید رمز کلاینت خود را بازیابی کنید.
- روی تأیید کلیک کنید. به صفحه «شناسههای کلاینت OAuth 2.0» باز خواهید گشت.
- شناسه کلاینت شما به پروژهتان اضافه خواهد شد. برای مشاهده جزئیات، روی آدرس URL شناسه کلاینت کلیک کنید.
افزودن کاربران آزمایشی
- در پنل سمت چپ، گزینهی «مخاطب» (Audience) را انتخاب کنید. باید ببینید که «وضعیت انتشار» (Publishing status) روی «در حال آزمایش» (Testing) و «نوع کاربر» (User type) روی «خارجی» (External) تنظیم شده است.
- در بخش «کاربران آزمایشی»، روی دکمه + افزودن کاربران کلیک کنید. آدرس ایمیل هر کاربری را که میخواهید اطلاعاتش را بازیابی کنید، وارد کنید.
- روی دکمه ذخیره کلیک کنید.
افزودن محدودهها به شناسه کلاینت
- در پنل سمت چپ، گزینه دسترسی به دادهها (Data Access) را انتخاب کنید.
- روی دکمهی افزودن یا حذف محدودهها کلیک کنید.
- در ستون API، عبارت "Google Health API" را جستجو کنید. برای این آزمایشگاه کد، ما از محدوده
.../auth/googlehealth.activity_and_fitness.readonlyاستفاده میکنیم. - پس از انتخاب محدوده، دکمه بهروزرسانی را فشار دهید تا به صفحه دسترسی به دادهها بازگردید.
- روی دکمه ذخیره کلیک کنید.
شما تنظیم شناسه کلاینت خود را به پایان رساندهاید.
۳. جریان مجوز را ایجاد کنید
- برنامه VS Code را روی دستگاه خود باز کنید.
- در صفحه خوشامدگویی، گزینه «باز کردن» را انتخاب کنید.
- یک پوشه برای ایجاد این پروژه انتخاب کنید و Open را بزنید. صفحه شما باید چیزی شبیه به این باشد که نام پوشه یا پروژه شما را در Explorer نشان میدهد.
- از منوی اصلی، گزینه File -> New Text file را انتخاب کنید.
- فایل را ذخیره کنید تا نامی برای آن انتخاب کنید. از منوی اصلی، File -> Save As -> Codelab.http را انتخاب کنید. با این کار، فایل در پروژه شما قرار میگیرد. پسوند فایل باید .http یا .rest باشد. برای این codelab، ما از .http استفاده میکنیم.
در طول این پروژه، ما چندین بار از مقادیر مختلف استفاده خواهیم کرد. این مقادیر عبارتند از:
| مقدار شناسه کلاینت از کنسول گوگل. |
| ارزش مخفی مشتری از کنسول گوگل. |
| یک نقطه پایانی در برنامه شما که کد مجوز را پردازش میکند. برای codelab، ما از https://www.google.com استفاده میکنیم. |
| توکن دسترسی که پس از اتمام جریان رضایت برای کاربر ایجاد میشود. |
| توکن بهروزرسانی که پس از پایان جریان رضایت برای کاربر ایجاد میشود. |
کد زیر را که متغیرهای مورد استفاده در این پروژه را تعریف میکند، اضافه کنید. آنها باید در بالای فایل Codelab.http قرار داشته باشند. مقادیر مربوط به client_id و secret را وارد کنید.
### File Variables for the Codelab
@client_id =
@secret =
@redirect_uri = https://www.google.com
@accessToken={{user.response.body.access_token}}
@refreshToken={{user.response.body.refresh_token}}
URL مجوز، که برای شروع جریان رضایت استفاده میشود، برای هر کاربری که میخواهید به دادههای او دسترسی داشته باشید، ارسال خواهد شد. برای ساخت URL مجوز، باید بدانیم که نقطه پایانی Google OAuth چیست و از پارامترهای پرس و جو برای مشخص کردن شناسه کلاینت، حوزههایی که میخواهیم به آنها دسترسی داشته باشیم و جایی که کاربر هنگام رضایت به حوزهها هدایت میشود، استفاده کنیم. مستندات کامل برای ساخت رشته مجوز Google را میتوانید در مستندات بیابید.
نقطه پایانی OAuth 2.0 گوگل در آدرس https://accounts.google.com/o/oauth2/v2/auth قرار دارد. این نقطه پایانی فقط از طریق HTTPS قابل دسترسی است. اتصالات HTTP ساده رد میشوند.
سرور احراز هویت گوگل از پارامترهای رشته پرسوجوی زیادی برای برنامههای وب سرور پشتیبانی میکند تا جریان احراز هویت را سفارشیسازی کند. ما از پارامترهای پرسوجوی مورد نیاز زیر استفاده خواهیم کرد: client_id ، redirect_uri ، response_type و scope . مستندات، فهرستی از تمام پارامترهای پرسوجو و توضیحات آنها را ارائه میدهد.
مقادیر پارامترهای پرس و جو عبارتند از
| مقدار شناسه کلاینت از کنسول گوگل |
| یک نقطه پایانی در برنامه شما که کد مجوز را پردازش میکند. برای codelab، از https://www.google.com استفاده کنید. |
| |
| محدودهها از کنسول گوگل با سینتکس https://www.googleapis.com و به دنبال آن نام محدوده میآیند. برای مثال، https://www.googleapis.com/auth/googlehealth.activity_and_fitness. |
بعد از متغیرها، آدرس مجوز خود را همانطور که نشان داده شده است بنویسید. پارامترهای تعریف شده در بالای پروژه را نمیتوان در رشته مجوز استفاده کرد. بنابراین، باید مقادیر مربوط به client_id و redirect_uri وارد کنیم. رشته client-id را با شناسه کلاینت خود جایگزین کنید.
### Google Health API Rest Client Example
### Authorization String
https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=https://www.google.com&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
وقتی کاربری رضایت خود را اعلام میکند، گوگل یک کد مجوز ارائه میدهد که شما با فراخوانی نقطه پایانی توکن گوگل، آن را با یک توکن دسترسی معاوضه میکنید. تعریف زیر را برای فراخوانی نقطه پایانی توکن به Codelab.http در زیر رشته مجوز اضافه کنید. در مرحله بعدی، authorization-code با یک کد مجوز جایگزین خواهید کرد.
### AUTHORIZATION ENDPOINTS
######################################################################
# @name user
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded
code=authorization-code&client_id={{clientId}}&client_secret={{secret}}&redirect_uri={{redirect_uri}}&grant_type=authorization_code
@name user به کاربر فعلی که به دادههای او دسترسی دارید اشاره میکند.
۴. یک حساب کاربری را مجاز کنید و توکنها را دریافت کنید
اکنون برای دریافت توکنهای مجوز، جریان مجوز را بررسی خواهیم کرد.
رشته مجوز در Codelab.http برای شروع جریان رضایت مبتنی بر مرورگر گوگل استفاده میشود. افزونه Rest Client ممکن است یک لینک ارسال درخواست برای این URL نمایش دهد. از ارسال درخواست برای این URL خاص استفاده نکنید. در عوض آن را کپی کرده و در مرورگر خود جایگذاری کنید، یا از Ctrl+Click (ویندوز/لینوکس) یا Cmd+Click (مک) در VS Code برای باز کردن آن در مرورگر پیشفرض خود استفاده کنید.
https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=https://www.google.com&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
- از شما خواسته میشود که وارد حساب گوگل خود شوید. باید با استفاده از یکی از حسابهای کاربری آزمایشی که در بخش افزودن کاربران آزمایشی پیکربندی کردهاید، وارد سیستم شوید.
- ممکن است پیامی مبنی بر عدم تأیید برنامه به شما نمایش داده شود. این به این دلیل است که برنامه منتشر نشده است. روی «ادامه» کلیک کنید.
- صفحه رضایت، فهرستی از حوزههای مورد درخواست را نشان میدهد. کاربر میتواند حوزههایی را که میخواهد با این برنامه به اشتراک بگذارد، انتخاب کند. روی «ادامه» کلیک کنید.
پس از موافقت با اشتراکگذاری محدودههای درخواستی، به redirect_uri که مشخص کردهاید (در این آزمایشگاه کد، https://www.google.com) هدایت میشوید. گوگل یک کد مجوز و پارامترهای دیگر را به redirect_uri اضافه میکند، بنابراین URL در نوار آدرس مرورگر شما باید چیزی شبیه به این باشد:
https://www.google.com/?code=4/0Ab32j93oyGWqaXE112sP1IKmh3kV1fE4tcHIMXYJQYWgNEtAa_0-YsfkS9Ekj3Be89u3fw&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
کد مجوز، مقداری الفبایی-عددی بین "code=" و "&scope" است. در مثال بالا، مقدار به صورت زیر است:
4/0Ab32j93oyGWqaXE112sP1IKmh3kV1fE4tcHIMXYJQYWgNEtAa_0-YsfkS9Ekj3Be89u3fw
در یک برنامه کاربردی، سرور شما این را از پارامترهای URL تجزیه میکند. برای این آزمایشگاه کد، کد مجوز را از URL در مرورگر خود کپی کنید.
حالا، این کد مجوز را با access_token و refresh_token عوض کنید. در Codelab.http ، در بدنه درخواست POST /token ، authorization-code با کد مجوزی که کپی کردهاید جایگزین کنید.
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded
code=authorization-code&client_id={{client_id}}&client_secret={{secret}}&redirect_uri={{redirect_uri}}&grant_type=authorization_code
روی لینک ارسال درخواست (Send Request) درست بالای خط POST https://oauth2.googleapis.com/token کلیک کنید.
پاسخ باید شبیه به این باشد:
{
"access_token": "ya29.a0ATi6K2uasci7FyyIClNLtQou6z...",
"expires_in": 3599,
"refresh_token": "1//05EuqYpEXjJCHCgYIA...",
"scope": "https://www.googleapis.com/auth/googlehealth.activity_and_fitness",
"token_type": "Bearer",
"refresh_token_expires_in": 604799
}
وقتی این پاسخ را دریافت میکنید، Rest Client به طور خودکار متغیرهای @accessToken و @refreshToken که در بالای Codelab.http تعریف شدهاند را برای استفاده در درخواستهای بعدی، پر میکند.
درباره توکنهای بهروزرسانی
وقتی کد مجوز را رد و بدل میکنید، پاسخ ممکن است علاوه بر 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 برای استفادههای بعدی به طور ایمن ذخیره کنید.
برای جزئیات بیشتر، به بهروزرسانی توکن دسترسی (دسترسی آفلاین) مراجعه کنید.
۵. اضافه کردن دادهها به برنامه موبایل Fitbit
برای کاربران جدید Fitbit، ممکن است در حساب Fitbit خود دادهای برای جستجو نداشته باشید. ما قصد داریم به صورت دستی یک گزارش تمرین اضافه کنیم که میتوانیم از طریق یکی از نقاط پایانی آن را جستجو کنیم. برای ثبت دستی یک تمرین، این مراحل را دنبال کنید:
- برنامه موبایل Fitbit را در دستگاه خود باز کنید. در صورت نیاز، وارد حساب Fitbit خود شوید.
- در گوشه پایین سمت راست صفحه، روی دکمه + ضربه بزنید.
- در بخش «ثبت دستی»، روی «فعالیت» ضربه بزنید
- نوع ورزش Walk (پیادهروی) را جستجو کرده و آن را انتخاب کنید.
- زمان شروع امروز را وارد کنید.
- مدت زمان را به ۱۵ دقیقه تغییر دهید.
- فاصله را ۱.۰ مایل (۱.۰ کیلومتر) در نظر بگیرید.
- روی افزودن ضربه بزنید.
- با نگه داشتن انگشت روی صفحه و کشیدن آن به پایین، برنامه تلفن همراه را با سرورهای Fitbit همگامسازی کنید. وقتی انگشت خود را بردارید، باید همگامسازی برنامه تلفن همراه را ببینید.
- در بخش «فعالیت»، باید ورودی پیادهروی ثبتشدهی دستی خود را ببینید.
۶. بازیابی دادهها با استفاده از متد list
برای فراخوانی متد list ، کد زیر را به Codelab.http ، درست زیر نقطه پایانی /token ، اضافه کنید.
### users.dataTypes.dataPoints
#####################################################
### LIST exercise
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer {{accessToken}}
Accept: application/json
این کد، نقطه پایانی list را فراخوانی میکند تا گامهای ثبتشده توسط کاربر در حساب Fitbit او را نمایش دهد. تعداد گامها برای هر دقیقه در پاسخ بازگردانده میشود، مشابه نقطه پایانی Fitbit Web API v1 Activity Intraday.
برای اجرای فراخوانی، روی لینک ارسال درخواست (Send Request) برای نقطه پایانی GET کلیک کنید. پاسخ شما باید مشابه این باشد:
{
"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": ""
}
بسیاری از نقاط پایانی از پارامترهای پرسوجو برای فیلتر کردن یا صفحهبندی پشتیبانی میکنند. برای مثال، exercise از فیلتر interval.civil_start_time پشتیبانی میکند. درخواست زیر را به Codelab.http اضافه کنید تا تمرینها را در یک محدوده زمانی خاص فهرست کنید:
### LIST exercise >= civil start time
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints?filter=exercise.interval.civil_start_time >= "2026-02-22T00:00:00"
Authorization: Bearer {{accessToken}}
Accept: application/json
۷. تبریک
تبریک میگویم!
شما بخش کدنویسی مقدماتی را به پایان رساندهاید و با موفقیت یاد گرفتهاید که چگونه از Visual Studio Code و افزونه Rest Client برای آزمایش احراز هویت OAuth 2.0 و برقراری تماس با نقاط پایانی API Google Health استفاده کنید. از اینجا، میتوانید نقاط پایانی اضافی را درست همانطور که در ابتدای بخش بازیابی دادهها با استفاده از متد List انجام دادید، اضافه کنید.
امیدواریم از ساخت برنامههایی که با اکوسیستم Google Health API ادغام میشوند، لذت ببرید. برای اطلاعات بیشتر، سایر نقاط پایانی Google Health API را در مستندات مرجع بررسی کنید و درباره Google OAuth 2.0 برای برنامههای وب سرور بیشتر بدانید.