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

API گوگل هلث به برنامه شما اجازه می‌دهد تا در صورت تغییر داده‌های سلامت کاربر، اعلان‌های بلادرنگ دریافت کند. به جای نظرسنجی برای تغییرات، سرور شما به محض اینکه داده‌ها در API گوگل هلث در دسترس قرار گیرند، یک درخواست HTTPS POST ( webhook ){:target="_blank" class="external"} دریافت می‌کند.

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

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

  • صورتجلسات منطقه فعال
  • سطح فعالیت
  • ارتفاع
  • قند خون
  • چربی بدن
  • کالری در منطقه ضربان قلب
  • تغییرپذیری روزانه ضربان قلب
  • محدوده‌های ضربان قلب روزانه
  • اشباع اکسیژن روزانه
  • میزان تنفس روزانه
  • ضربان قلب در حالت استراحت روزانه
  • مشتقات دمای خواب روزانه
  • فاصله
  • ورزش
  • طبقات
  • ضربان قلب
  • تغییرپذیری ضربان قلب
  • ارتفاع
  • گزارش هیدراتاسیون
  • گزارش تغذیه
  • خلاصه خواب با نرخ تنفس
  • حداکثر اکسیژن مصرفی (Vo2 Max) را بدوید
  • دوره کم تحرکی
  • خواب
  • مراحل
  • زمان در منطقه ضربان قلب
  • کل کالری
  • وزن

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

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

حساب‌های سرویس IAM

اگرچه الزامی نیست، اما توصیه می‌کنیم هنگام پیکربندی مشترکین برای API گوگل هلث، از یک حساب سرویس IAM استفاده کنید. حساب‌های سرویس در مقایسه با حساب‌های کاربری استاندارد، از طریق ویژگی‌های زیر، امنیت بهتری را برای حجم کاری برنامه‌ها فراهم می‌کنند:

  • اعتبارنامه‌های کوتاه‌مدت خودکار: وقتی به یک محیط اجرای Google Cloud (مانند Compute Engine، Cloud Run یا Google Kubernetes Engine) متصل می‌شوید، حساب‌های سرویس به‌طور خودکار اعتبارنامه‌های کوتاه‌مدت امن را دریافت و جابه‌جا می‌کنند. این امر خطرات مدیریت و ذخیره‌سازی کلیدهای استاتیک پایدار را از بین می‌برد.
  • اصل حداقل امتیاز: حساب‌های کاربری سرویس، هویت‌های اختصاصی برای بارهای کاری ارائه می‌دهند. شما می‌توانید فقط مجوزهای خاص مورد نیاز برای مدیریت نقاط پایانی مشترکین را به آنها اعطا کنید و از دسترسی گسترده‌تر به منابع Google Cloud خود جلوگیری کنید.
  • استقلال در چرخه عمر: حساب‌های کاربری سرویس مستقل از هر حساب کاربری جداگانه عمل می‌کنند و تضمین می‌کنند که تغییرات پرسنلی بر ثبات احراز هویت در درازمدت تأثیری نداشته باشد.

تنظیم حساب کاربری سرویس

برای پیکربندی برنامه مشترک خود برای تأیید اعتبار با استفاده از یک حساب سرویس:

  1. ایجاد یک حساب کاربری سرویس: در کنسول Google Cloud، به صفحه IAM & Admin پروژه خود بروید تا یک حساب کاربری سرویس جدید تحت مدیریت کاربر ایجاد کنید .
  2. اعطای نقش‌های لازم IAM: به حساب سرویس، نقش‌های مناسب مورد نیاز برای مدیریت مشترکین در پروژه Google Cloud خود را اختصاص دهید .
  3. حساب سرویس را به حجم کار خود متصل کنید: محیطی که منطق مشترک شما را میزبانی می‌کند، طوری پیکربندی کنید که به عنوان حساب سرویس جدید اجرا شود . این به کد برنامه شما (مانند کتابخانه‌های کلاینت API گوگل) اجازه می‌دهد تا هنگام فراخوانی REST API projects.subscribers به طور خودکار اعتبارنامه‌های کوتاه مدت حساب سرویس را شناسایی و استفاده کند.

نقش‌های CPE

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

  • خواندن API سلامت گوگل
  • ویرایشگر API سلامت گوگل
  • مدیر API سلامت گوگل

درباره نقش‌ها و مجوزهای IAM مربوط به API گوگل هلث بیشتر بدانید .

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

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

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

ایجاد مشترک

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

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

در 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": {
    "secret": "Bearer example-secret-token"
  }
}

پاسخ 

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

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

از نقطه پایانی 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",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "totalSize": 1
}

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

از نقطه پایانی 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",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ]
}

حذف مشترک

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

درخواست 

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

پاسخ

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

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

برای اطمینان از امنیت و قابلیت اطمینان در ارسال اعلان‌ها، 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 را پس از تأیید موفقیت‌آمیز بودن مرحله ۲ بپذیرد.

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

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

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

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

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

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

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

اگر مشترک شما با سیاست subscription_create_policy برای انواع داده‌های خاص پیکربندی شده است، باید به صراحت برای هر کاربر اشتراک ایجاد و مدیریت کنید. یک اشتراک، یک کاربر خاص را برای مجموعه‌ای از انواع داده تعریف شده به نقطه پایانی مشترک شما پیوند می‌دهد. توسعه‌دهندگان می‌توانند از APIهای خاص برای موارد زیر استفاده کنند:

  • ایجاد (دستی) اشتراک‌ها به ازای هر healthUserId - یک اشتراک جدید برای یک کاربر خاص ایجاد می‌کند. این روش مستلزم آن است که مشترک، SubscriptionCreatePolicy را برای انواع داده‌های درخواستی روی MANUAL تنظیم کرده باشد.
  • به‌روزرسانی (دستی) اشتراک - انواع داده را برای اشتراک کاربر موجود به‌روزرسانی می‌کند.
  • حذف اشتراک (دستی) - اشتراک یک کاربر خاص را حذف می‌کند. پس از حذف، نقطه پایانی مشترک شما دیگر اعلان‌هایی برای این کاربر برای انواع داده‌های مرتبط دریافت نخواهد کرد.
  • فهرست اشتراک‌ها (دستی) - تمام اشتراک‌های فعال برای یک مشترک مشخص را فهرست می‌کند. می‌توانید نتایج را بر اساس کاربر یا نوع داده فیلتر کنید.

اعلان‌ها

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

قالب اعلان

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

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-03-08T01: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
    });
});

تأیید امضا

برای اطمینان از صحت اعلان‌های Webhooks، فایل JSON خام هر اعلان Webhook خروجی با یک کلید خصوصی با استفاده از PublicKeySign شرکت Tink امضا می‌شود و امضای رمزگذاری شده Base64 را در هدر HTTP مربوط به GOOGLE-HEALTH-API-SIGNATURE در درخواست ارائه می‌دهد. این کلیدهای امضا به طور خودکار هر 30 روز یکبار تغییر می‌کنند و مجموعه کلید عمومی رسمی مربوطه به عنوان یک فایل JSON در آدرس اینترنتی دائمی https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json توزیع می‌شود.

نحوه تأیید امضا

استفاده از Tink (توصیه شده) : توسعه‌دهندگان می‌توانند امضا را با استفاده از PublicKeyVerify اولیه Tink تأیید کنند. مجموعه کلید عمومی را از URL دائمی دریافت کنید، PublicKeyVerify اولیه را با مجموعه کلید نمونه‌سازی کنید و هدر رمزگشایی شده GOOGLE-HEALTH-API-SIGNATURE را در برابر بار داده خام webhook JSON تأیید کنید.

تأیید دستی (بدون Tink) : اگر توسعه‌دهندگان تصمیم به استفاده از Tink نداشته باشند، می‌توانند با دنبال کردن این مراحل، امضا را به صورت دستی تأیید کنند:

  1. Base64-سرآیند GOOGLE-HEALTH-API-SIGNATURE را رمزگشایی می‌کند تا پیشوند ۵ بایتی Tink (که شامل یک پیشوند نسخه ۱ بایتی و یک keyId ۴ بایتی است) را از امضای واقعی رمزگذاری شده توسط DER جدا کند.
  2. مجموعه کلید JSON را از https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json دریافت کنید.
  3. کلید منطبق با keyId تجزیه‌شده را پیدا کنید و فیلد مقدار آن را که حاوی یک بافر پروتکل EcdsaPublicKey سریالی‌شده است، با Base64-decode کنید.
  4. مختصات x و y مربوط به تابع big-endian (برچسب‌های ۳ و ۴ پروتوباف) را از این فایل باینری استخراج کنید.
  5. با استفاده از مختصات x و y استخراج‌شده، یک کلید عمومی استاندارد ECDSA P-256 را در یک کتابخانه رمزنگاری داخلی نمونه‌سازی کنید.
  6. با استفاده از الگوریتم SHA-256، محتوای خام JSON وب‌هوک را در برابر امضای DER استخراج‌شده تأیید کنید.

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

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

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

خطاهای رایج

کد خطا پیام توضیحات توصیه
درخواست بد ۴۰۰ شماره پروژه نامعتبر در نام منبع هنگام حذف یا به‌روزرسانی مشترک، از شناسه پروژه Google Cloud خود در URL درخواست به جای شماره پروژه استفاده کنید. این امر در مورد اشتراک‌های webhook با استفاده از نقطه پایانی projects.subscribers صدق می‌کند. از شماره پروژه گوگل کلود خود در URL درخواست استفاده کنید، نه از شناسه پروژه.
۴۰۳ ممنوعه تماس گیرنده مجوز ندارد هنگام ایجاد یا فهرست کردن مشترکین، از شناسه پروژه Google Cloud خود در URL درخواست به جای شماره پروژه استفاده کنید. این امر در مورد اشتراک‌های وب‌هوک با استفاده از نقطه پایانی projects.subscribers صدق می‌کند. از شماره پروژه گوگل کلود خود در URL درخواست استفاده کنید، نه از شناسه پروژه.

قبلی
پیوندهای جهانی و برنامه
بعدی
عیب یابی