اشتراک‌های وب‌هوک

اشتراک‌ها به زودی اضافه می‌شوند.

API گوگل هلث به برنامه شما اجازه می‌دهد تا هنگام تغییر داده‌های سلامت کاربر، اعلان‌های بلادرنگ دریافت کند. به جای نظرسنجی برای تغییرات، سرور شما به محض اینکه داده‌ها در API گوگل هلث در دسترس قرار گیرند، یک درخواست HTTPS POST ( وب‌هوک ) دریافت می‌کند.

انواع داده پشتیبانی شده

اعلان‌های وب‌هوک برای انواع داده‌های زیر پشتیبانی می‌شوند:

• مراحل
• ارتفاع
• فاصله
• طبقات
• وزن
• خواب

اعلان‌ها برای این نوع داده‌ها فقط زمانی ارسال می‌شوند که کاربر برای یکی از حوزه‌های مربوطه رضایت داده باشد:

• Activity که انواع داده‌های گام‌ها، ارتفاع، مسافت و طبقات را پوشش می‌دهد:
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• معیارهای سلامت ، که نوع داده وزن را پوشش می‌دهد:
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
• Sleep ، که نوع داده sleep را پوشش می‌دهد:
  • https://www.googleapis.com/auth/googlehealth.sleep
  • https://www.googleapis.com/auth/googlehealth.sleep.readonly

مدیریت مشترکین

قبل از اینکه بتوانید اعلان‌ها را دریافت کنید، باید یک مشترک (Subscriber) ثبت کنید که نشان‌دهنده‌ی نقطه‌ی پایانی اعلان برنامه‌ی شماست. می‌توانید مشترکین را با استفاده از REST API موجود در projects.subscribers مدیریت کنید.

نقطه پایانی مشترک شما باید از HTTPS (TLSv1.2+) استفاده کند و به صورت عمومی قابل دسترسی باشد. در طول ایجاد و به‌روزرسانی‌های مشترک، API Google Health یک چالش تأیید انجام می‌دهد تا مطمئن شود که شما مالک URI نقطه پایانی هستید. اگر تأیید ناموفق باشد، عملیات ایجاد و به‌روزرسانی مشترک با خطای FailedPreconditionException با شکست مواجه می‌شود.

ایجاد مشترک

برای ثبت یک مشترک جدید برای پروژه خود، از نقطه پایانی create استفاده کنید. شما باید موارد زیر را ارائه دهید:

• endpointUri : آدرس اینترنتی مقصد برای اعلان‌های وب‌هوک.
• subscriberConfigs : انواع داده‌هایی که می‌خواهید برای آنها اعلان دریافت کنید و سیاست اشتراک برای هر کدام.
• endpointAuthorization : مکانیزم مجوزدهی برای نقطه پایانی شما. این باید حاوی یک authorization_token باشد که شما ارائه می‌دهید. مقدار authorization_token در هدر Authorization با هر پیام اعلان ارسال می‌شود. می‌توانید از این توکن برای تأیید اینکه درخواست‌های ورودی از API Google Health هستند استفاده کنید. به عنوان مثال، می‌توانید authorization_token برای احراز هویت Bearer روی Bearer R4nd0m5tr1ng123 یا برای احراز هویت Basic dXNlcjpwYXNzd29yZA== تنظیم کنید.
• subscriberId : یک شناسه منحصر به فرد که برای مشترک ارائه می‌دهید. این شناسه باید بین ۴ تا ۳۶ کاراکتر باشد و با عبارت منظم ( [az]([a-z0-9-]{2,34}[a-z0-9]) ) مطابقت داشته باشد.

در subscriberConfigs باید برای هر نوع داده، subscriptionCreatePolicy تنظیم کنید. برای استفاده از اشتراک‌های خودکار، آن را روی AUTOMATIC و اگر قصد دارید خودتان اشتراک‌های کاربران را مدیریت کنید، آن را روی MANUAL تنظیم کنید. برای جزئیات بیشتر در مورد هر گزینه ، به اشتراک‌های خودکار و اشتراک‌های دستی مراجعه کنید.

درخواست

POST https://health.googleapis.com/v4/projects/project-id/subscribers?subscriberId=subscriber-id
{
  "endpointUri": "https://myapp.com/webhooks/health",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorization_token": "Bearer example-secret-token"
  }
}

پاسخ

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

مشترکین را فهرست کنید

از نقطه پایانی list برای بازیابی تمام مشترکین ثبت شده برای پروژه خود استفاده کنید.

درخواست

GET https://health.googleapis.com/v4/projects/project-id/subscribers

پاسخ

{
  "subscribers": [
    {
      "name": "projects/project-id/subscribers/subscriber-id",
      "endpointUri": "https://myapp.com/webhooks/health",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

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

از نقطه پایانی patch برای به‌روزرسانی یک مشترک در پروژه خود استفاده کنید. فیلدهایی که می‌توانند به‌روزرسانی شوند عبارتند از endpointUri ، subscriberConfigs و endpointAuthorization .

شما فیلدها را با ارائه یک پارامتر کوئری updateMask و یک بدنه درخواست به‌روزرسانی می‌کنید. updateMask باید شامل فهرستی از نام فیلدهایی باشد که می‌خواهید به‌روزرسانی کنید و با استفاده از حروف بزرگ (cama case) از هم جدا شده‌اند (برای مثال، endpointUri ). بدنه درخواست باید شامل یک شیء Subscriber جزئی با مقادیر جدید برای فیلدهایی باشد که می‌خواهید به‌روزرسانی کنید. فقط فیلدهایی که در updateMask مشخص شده‌اند به‌روزرسانی می‌شوند. اگر فیلدهایی را در بدنه درخواست ارائه دهید که در updateMask نیستند، نادیده گرفته می‌شوند.

اگر endpointUri یا endpointAuthorization را به‌روزرسانی کنید، تأیید نقطه پایانی انجام می‌شود. برای جزئیات بیشتر به تأیید نقطه پایانی مراجعه کنید.

هنگام به‌روزرسانی subscriberConfigs ، توجه داشته باشید که این یک جایگزینی کامل است، نه ادغام. اگر subscriberConfigs در updateMask گنجانده شده باشد، تمام پیکربندی‌های ذخیره شده برای آن مشترک با لیستی که در بدنه درخواست ارائه شده است، بازنویسی می‌شوند. برای اضافه کردن یا حذف یک پیکربندی، باید مجموعه کامل پیکربندی‌ها را ارائه دهید. اگر فیلدهای دیگری را به‌روزرسانی می‌کنید و می‌خواهید پیکربندی‌های فعلی خود را حفظ کنید، subscriberConfigs از updateMask حذف کنید.

درخواست

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

پاسخ

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/new-webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

تأیید نقطه پایانی

برای اطمینان از امنیت و قابلیت اطمینان در ارسال اعلان‌ها، API گوگل هلث هر زمان که مشترکی ایجاد می‌کنید یا پیکربندی نقطه پایانی آن ( endpointUri یا endpointAuthorization ) را به‌روزرسانی می‌کنید، یک تأیید دو مرحله‌ای اجباری انجام می‌دهد. این فرآیند به صورت همزمان در طول فراخوانی API انجام می‌شود. این سرویس دو درخواست POST خودکار را با استفاده از User-Agent Google-Health-API-Webhooks-Verifier با بدنه JSON {"type": "verification"} به URI نقطه پایانی شما ارسال می‌کند.

• دست‌دهی مجاز : اولین درخواست با هدر Authorization پیکربندی‌شده شما ارسال می‌شود. سرور شما باید با وضعیت 200 OK یا 201 Created پاسخ دهد.
• چالش غیرمجاز : درخواست دوم بدون اعتبارنامه ارسال می‌شود. سرور شما باید با وضعیت 401 Unauthorized یا 403 Forbidden پاسخ دهد.

این handshake تأیید می‌کند که نقطه پایانی شما فعال است و امنیت را به درستی اعمال می‌کند. اگر هر یک از مراحل با شکست مواجه شود، درخواست API با خطای FAILED_PRECONDITION با شکست مواجه می‌شود. تنها پس از موفقیت این handshake، مشترک شما ذخیره و برای دریافت اعلان‌های داده‌های سلامت فعال می‌شود.

چرخش کلید

اگر نیاز دارید که کلیدها را برای endpointAuthorization بچرخانید، این مراحل را دنبال کنید:

1. نقطه پایانی خود را طوری پیکربندی کنید که مقادیر endpointAuthorization قدیمی و جدید را بپذیرد.
2. پیکربندی مشترک را با مقدار جدید endpointAuthorization با استفاده از درخواست patch با ?updateMask=endpointAuthorization به‌روزرسانی کنید.
3. نقطه پایانی خود را طوری پیکربندی کنید که فقط مقدار جدید endpointAuthorization را پس از تأیید موفقیت‌آمیز بودن مرحله ۲ بپذیرد.

حذف مشترک

از نقطه پایانی delete برای حذف یک مشترک از پروژه خود استفاده کنید. پس از حذف، مشترک دیگر اعلان‌ها را دریافت نخواهد کرد.

درخواست

DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id

پاسخ

در صورت موفقیت‌آمیز بودن حذف، یک بدنه پاسخ خالی با وضعیت HTTP `200 OK` بازگردانده می‌شود.

{}

اشتراک‌های کاربری

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

اشتراک‌های خودکار

ما استفاده از اشتراک‌های خودکار را توصیه می‌کنیم. برای فعال کردن این ویژگی، در subscriberConfigs خود، برای انواع داده‌های خاص، subscriptionCreatePolicy روی AUTOMATIC تنظیم کنید. dataTypes که با یک سیاست AUTOMATIC مشخص می‌کنید، همان انواع داده‌هایی هستند که API Google Health برای آنها اعلان ارسال می‌کند، مشروط بر اینکه رضایت کاربر نیز برای آن انواع داده‌ها اعطا شده باشد.

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

اگر کاربری رضایت خود را لغو کند، اعلان‌های مربوط به انواع داده‌های مربوطه متوقف می‌شوند. اشتراک‌های خودکار توسط گوگل مدیریت می‌شوند و نمی‌توان آنها را به صورت جداگانه فهرست یا حذف کرد؛ آنها فقط زمانی حذف می‌شوند که مشترک والد حذف شود.

اشتراک‌های دستی

اگر ترجیح می‌دهید اشتراک‌ها را برای هر کاربر به صورت دستی مدیریت کنید، در subscriberConfigs subscriptionCreatePolicy روی MANUAL تنظیم کنید. با این سیاست، اشتراک‌های کاربر به طور خودکار ایجاد نمی‌شوند. این قابلیت در آینده، زمانی که APIها برای مدیریت اشتراک‌های دستی در دسترس قرار گیرند، استفاده خواهد شد. تا زمانی که این APIها در دسترس قرار گیرند، توصیه می‌کنیم از اشتراک‌های AUTOMATIC استفاده کنید.

اعلان‌ها

وقتی داده‌های کاربر برای یک نوع داده مشترک تغییر می‌کند، API گوگل هلث یک درخواست HTTPS POST به آدرس اینترنتی (URL) مشترک ارسال می‌کند.

قالب اعلان

بار داده‌ی اعلان یک شیء JSON است که حاوی جزئیاتی در مورد تغییر داده‌ها است. این شامل شناسه‌ی کاربر، نوع داده و فواصل زمانی است که می‌توانید برای جستجوی داده‌های به‌روزرسانی‌شده از آنها استفاده کنید.

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-03-0B01:29:00Z",
          "endTime": "2026-03-08T01:34:00Z"
        },
        "civilDateTimeInterval": {
          "startDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 29
            }
          },
          "endDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 34
            }
          }
        },
        "civilIso8601TimeInterval": {
          "startTime": "2026-03-07T17:29:00",
          "endTime": "2026-03-07T17:34:00"
        }
      }
    ]
  }
}

فیلد operation ، نوع تغییری که باعث ایجاد اعلان شده است را نشان می‌دهد:

• UPSERT : برای هرگونه افزودن یا اصلاح داده ارسال می‌شود.
• DELETE : زمانی ارسال می‌شود که کاربر داده‌ها را حذف می‌کند، یا زمانی که داده‌ها به دلیل یک رویداد سیستمی، مانند لغو مجوز توسط کاربر یا حذف حساب کاربری، حذف می‌شوند.

توصیه می‌کنیم منطق مدیریت اعلان‌های خود را idempotent کنید، مخصوصاً برای عملیات UPSERT ، زیرا تلاش‌های مجدد می‌توانند باعث ارسال اعلان‌های تکراری شوند.

فیلد clientProvidedSubscriptionName یک شناسه منحصر به فرد است. برای اشتراک‌هایی با خط‌مشی MANUAL ، این فیلد حاوی نام اشتراک ارائه شده توسط توسعه‌دهنده است که هنگام ایجاد اشتراک مشخص شده است. این یک شناسه پایدار برای مدیریت اشتراک‌های دستی فراهم می‌کند. برای اشتراک‌هایی که با خط‌مشی AUTOMATIC ایجاد می‌شوند، API Google Health به طور خودکار یک شناسه منحصر به فرد (یک UUID تصادفی) برای هر اعلان ایجاد و به این فیلد اختصاص می‌دهد. گنجاندن clientProvidedSubscriptionName برای هر دو خط‌مشی دستی و خودکار، فرمت بار اعلان ثابتی را در همه انواع اشتراک تضمین می‌کند.

شناسه healthUserId یک شناسه API گوگل هلث برای کاربری است که داده‌هایش تغییر کرده است. اگر برنامه شما از چندین کاربر پشتیبانی می‌کند، می‌توانید برای هر کاربری که رضایت برنامه شما را پذیرفته است، اعلان دریافت کنید. وقتی اعلانی دریافت می‌کنید، از شناسه healthUserId برای شناسایی اینکه داده‌های کدام کاربر تغییر کرده است استفاده کنید، بنابراین می‌توانید از اعتبارنامه‌های OAuth آنها برای جستجوی داده‌هایشان استفاده کنید.

برای نگاشت اعتبارنامه‌های OAuth یک کاربر به healthUserId او، از نقطه پایانی getIdentity استفاده کنید. این نقطه پایانی را با اعتبارنامه‌های کاربر در طول فرآیند ورود کاربر فراخوانی کنید تا healthUserId او را بازیابی کرده و این نگاشت را ذخیره کنید. این نگاشت با گذشت زمان تغییر نمی‌کند، بنابراین می‌توان آن را به طور نامحدود ذخیره کرد. برای مثال، به Get user ID مراجعه کنید. این به شما امکان می‌دهد هنگام جستجوی داده‌ها بر اساس healthUserId در یک اعلان، اعتبارنامه‌های صحیح کاربر را انتخاب کنید.

پاسخ به یک اعلان

سرور شما باید بلافاصله به اعلان‌هایی که کد وضعیت HTTP 204 No Content دارند پاسخ دهد. برای جلوگیری از وقفه‌های زمانی، پس از ارسال پاسخ، محتوای اعلان را به صورت ناهمزمان پردازش کنید. اگر API سلامت گوگل کد وضعیت دیگری دریافت کند یا مهلت درخواست تمام شود، بعداً دوباره سعی می‌کند اعلان را ارسال کند.

مثال Node.js (اکسپرس):

app.post('/webhook-receiver', (req, res) => {
    // 1. Immediately acknowledge the notification
    res.status(204).send();

    // 2. Process the data asynchronously in the background
    const notification = req.body;
    setImmediate(() => {
        console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
        // Trigger your data retrieval logic here
    });
});

وضعیت مشترک و بازیابی

اگر نقطه پایانی مشترک شما از دسترس خارج شود یا کد وضعیت خطا (هر چیزی غیر از 204 ) را برگرداند، API سلامت گوگل اعلان‌های در انتظار را تا 7 روز ذخیره می‌کند و با یک روند کاهشی نمایی، دوباره تلاش می‌کند تا آنها را ارسال کند.

به محض اینکه دستگاه شما دوباره آنلاین شود و با 204 پاسخ دهد، API به طور خودکار انبوه پیام‌های ذخیره شده را ارسال می‌کند. اعلان‌هایی که بیش از ۷ روز از تاریخ ارسال آنها گذشته باشد، حذف می‌شوند و قابل بازیابی نیستند.