نقطه‌های پایانی

این صفحه مروری بر قراردادهای REST API، به همراه فهرستی از وظایف رایج Google Health API و نمونه‌هایی از هر کدام ارائه می‌دهد.

قراردادهای REST API

رابط برنامه‌نویسی کاربردی گوگل هلث (Google Health API) از استانداردهای پیشنهادهای بهبود رابط کاربری گوگل (AIP) ، به‌ویژه AIP-127 (ترانس‌کدینگ HTTP و gRPC) و AIP-131 تا AIP-135 (روش‌های استاندارد) پیروی می‌کند. این استانداردها نحوه نگاشت داده‌ها از یک پیام اولیه به یک درخواست HTTP را تعریف می‌کنند.

پارامترهای پرس و جو

پارامترهای پرس‌وجو زمانی استفاده می‌شوند که داده‌ها بخشی از URL باشند. این در درجه اول برای درخواست‌های GET (دریافت یک منبع) یا درخواست‌های LIST (فیلتر کردن/صفحه‌بندی) است، اما برای عملیات DELETE نیز استفاده می‌شود.

  • محل قرارگیری : بعد از علامت ? به آدرس اینترنتی (URL) اضافه می‌شود.
  • نحو : جفت‌های کلید-مقدار با & از هم جدا می‌شوند.
  • نگاشت : هر فیلدی در پیام درخواست که بخشی از الگوی مسیر URL نیست، به یک پارامتر پرس‌وجو نگاشت می‌شود.
  • مناسب برای : انواع داده ساده (رشته‌ها، اعداد صحیح، اعداد شمارشی) و فیلدهای تکراری.

مثال نحوی:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

درخواست بدنه

بدنه درخواست زمانی استفاده می‌شود که داده‌ها وضعیت یک منبع را تغییر می‌دهند یا برای یک URL خیلی بزرگ هستند. بدنه معمولاً یک نمایش JSON از خود منبع است. معمولاً برای عملیات POST ، PATCH و PUT استفاده می‌شود.

  • محل قرارگیری : درون بار داده HTTP (در URL قابل مشاهده نیست).
  • سینتکس : به صورت یک شیء JSON قالب‌بندی شده است.
  • نگاشت : در حاشیه‌نویسی google.api.http تعریف شده است.
    • body: "*" به این معنی است که کل پیام بدنه است.
    • body: "resource_name" یعنی فقط یک فیلد خاص در پروتو، بدنه است.
  • بهترین برای : اشیاء پیچیده، پیام‌های تو در تو و داده‌های حساس.

مثال نحوی:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

مورد ترکیبی

در یک متد Update منطبق با AIP-134 یا یک عملیات PATCH ، هر دو استفاده می‌شوند. URL شامل نام منبع، بدنه شامل داده‌های منبع به‌روزرسانی‌شده و یک پارامتر پرس‌وجو (معمولاً update_mask ) مشخص می‌کند که کدام فیلدها باید تغییر کنند.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

تفاوت‌های کلیدی در یک نگاه

ویژگی پارامترهای پرس و جو درخواست بدنه
راهنمایی AIP برای عملیات جستجو، فیلتر کردن و خواندن استفاده می‌شود. برای عملیات نوشتن استفاده می‌شود.
قابلیت مشاهده در تاریخچه مرورگر و لاگ‌های سرور قابل مشاهده است. از آدرس اینترنتی (URL) پنهان شده است.
پیچیدگی محدود به ساختارهای مسطح یا تکراری. از اشیاء JSON تو در تو و عمیق پشتیبانی می‌کند.
رمزگذاری باید با URL کدگذاری شود (برای مثال، فاصله‌ها به %20 تبدیل می‌شوند). کدگذاری استاندارد JSON

خرما

تمام تاریخ‌ها در API گوگل هلث با فرمت YYYY-MM-DD نمایش داده می‌شوند. API تغذیه از استاندارد ISO-8601 برای مقادیر تاریخ با شرایط زیر پشتیبانی می‌کند:

  • یک سال چهار رقمی YYYY
  • مقادیر سال در محدوده ۰۰۰۰-۹۹۹۹
  • عدم اعمال محدودیت‌های تاریخ شروع مندرج در استاندارد ISO-8601 یا سایر استانداردهای دوره‌ای

سربرگ‌ها

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

Authorization: Bearer access-token
Accept: application/json

فهرست وظایف API

این بخش فهرستی از وظایف رایج API سلامت گوگل و نمونه‌هایی از هر کدام را ارائه می‌دهد.

شناسه کاربری Fitbit یا Google را دریافت کنید

پس از اینکه کاربر از طریق Google OAuth 2.0 رضایت خود را اعلام کرد، پاسخ توکن حاوی شناسه کاربری Fitbit یا Google نیست. برای دریافت شناسه کاربری، نقطه پایانی getIdentity را فراخوانی کنید. getIdentity هم شناسه کاربری قدیمی Fitbit و هم شناسه کاربری Google را برمی‌گرداند.

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

برای مثال:

درخواست 

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

پاسخ 

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

داده‌های روزانه یا داده‌های دقیقی را که در طول روز جمع‌آوری شده‌اند، دریافت کنید

از نقطه پایانی list برای یک نوع داده خاص استفاده کنید تا داده‌های درون‌روزی یا جزئی جمع‌آوری‌شده در طول روز را در فواصل پشتیبانی‌شده برای آن نوع داده دریافت کنید.

برای مثال:

درخواست 

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

پاسخ 

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

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

از نقطه پایانی list به همراه یک پارامتر filter برای فیلتر کردن داده‌ها بر اساس زمان مدنی یا یک بازه زمانی استفاده کنید.

برای مثال:

درخواست 

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

پاسخ 

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

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

از نقطه پایانی list به همراه یک پارامتر filter برای فیلتر کردن داده‌ها بر اساس زمان فیزیکی مشاهده نمونه استفاده کنید.

برای مثال:

درخواست 

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

پاسخ 

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "-->bodyFat<--": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

فیلتر کردن داده‌ها بر اساس منابع داده مانند گجت‌های پوشیدنی

از نقطه پایانی reconcile برای دریافت داده‌ها برای یک "خانواده منبع داده" خاص استفاده کنید. برای انجام این کار، پارامتر dataSourceFamily را به عنوان پارامتر پرس و جو مشخص کنید.

جدول زیر گزینه‌های پشتیبانی‌شده‌ی dataSourceFamily را شرح می‌دهد:

گزینه توضیحات
users/me/dataSourceFamilies/all-sources مقدار پیش‌فرض. شامل داده‌ها از تمام منابع داده موجود است.
users/me/dataSourceFamilies/google-wearables شامل داده‌های دستگاه‌های ردیاب گوگل و فیت‌بیت (مانند ردیاب‌های فیت‌بیت و پیکسل واچ) می‌شود. داده‌های ثبت‌شده دستی را شامل نمی‌شود.
users/me/dataSourceFamilies/google-sources شامل داده‌های شخص ثالث گوگل، مانند داده‌های دستگاه‌های ردیاب و داده‌های ثبت‌شده دستی می‌شود.

در اینجا مثالی از فیلتر کردن فقط خواب ثبت‌شده توسط ردیاب برای روز بعد از 2026-03-03 آورده شده است:

درخواست 

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

پاسخ 

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
…
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

جمع‌آوری نقاط داده در یک بازه زمانی مشخص

از نقطه پایانی rollUp برای بازگرداندن مجموع نقاط داده بر اساس یک پنجره در واحد ثانیه، در محدوده datetime بر اساس زمان فیزیکی کاربر (به UTC) استفاده کنید.

هنگام فراخوانی نقطه پایانی rollUp ، باید بدنه درخواست را که نشان‌دهنده محدوده تاریخ مورد نیاز در زمان مدنی کاربر است، ارائه دهید. برای مثال:

درخواست 

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-02-17T17:00:00Z",
    "endTime": "2026-02-17T17:59:59Z"
  },
  "windowSize": "30s"
}

پاسخ 

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:55:30Z",
      "steps": {
        "countSum": "41"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:54:30Z",
      "steps": {
        "countSum": "31"
      }
    },
...
  ]
}

جمع‌آوری داده‌ها در طول یک روز یا چند روز

نقطه پایانی dailyRollUp باید زمانی استفاده شود که می‌خواهید داده‌ها را در طول یک روز یا چند روز، که به عنوان windowSize شناخته می‌شود، جمع‌آوری کنید. محدوده زمانی مدنی بسته-باز را برای بازه مورد نیاز در بدنه درخواست ارائه دهید. بسته به نوع داده، یا مجموع یا میانگین را در بازه دریافت خواهید کرد.

برای مثال:

درخواست 

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 23,
        "minutes": 59,
        "seconds": 59,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1
}

پاسخ 

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "3822"
      }
    }
  ]
}

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

از نقطه پایانی patch برای درج یا به‌روزرسانی داده‌های برنامه Fitbit کاربر استفاده کنید.

در اینجا مثالی آورده شده است که در آن یک کاربر چربی بدن خود را در ترازویی به نام "HumanScale" از شرکت "Scales R Us" ثبت کرده است. میزان چربی بدن جدید کاربر برای تاریخ 2026-03-10، 20٪ است.

درخواست 

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
content-length: 329

{
  "name": "bodyFatName",
  "dataSource": {

    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

پاسخ 

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z"
      },
      "percentage": 20
    }
  }
}

یک ماده غذایی را ثبت کنید

برای ثبت یک ماده غذایی، یک درخواست POST به نقطه پایانی نقاط داده nutrition-log ارسال کنید. بدنه درخواست شامل یک DataPoint با یک شیء nutritionLog است. برای اطلاعات بیشتر، به راهنمای Nutrition مراجعه کنید.

برای مثال:

درخواست 

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "nutritionLog": {
    "interval": {
      "startTime": "2026-06-16T12:00:00Z",
      "endTime": "2026-06-16T12:30:00Z"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

پاسخ 

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/2515055256096816351/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

حذف داده‌های سلامت کاربر

از نقطه پایانی batchDelete برای حذف آرایه‌ای از داده‌های برنامه Fitbit کاربر استفاده کنید.

در اینجا مثالی آورده شده است که در آن کاربر قبلاً چربی بدن خود را روی ترازو ثبت کرده است، اما می‌خواهد این رکورد را حذف کند. با استفاده از user-id و data-point-id از عمل درج اصلی:

درخواست 

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

پاسخ 

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

اطلاعات دستگاه را پیدا کنید

از نقطه پایانی list برای بازیابی لیست دستگاه‌های جفت‌شده با حساب کاربری استفاده کنید. این شامل اطلاعات مدل دستگاه ( deviceVersion ) و آخرین باری که با برنامه موبایل Google Health ( lastSyncTime ) همگام‌سازی شده است، می‌شود.

پیکربندی لیست و اطلاعات همگام‌سازی برای عیب‌یابی مشکلات همگام‌سازی یا بازیابی داده‌های تاریخی از آخرین زمان همگام‌سازی مفید است.

برای مثال:

درخواست 

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

پاسخ 

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

پرس و جو از داده‌های تاریخی

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

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

  • صفحه‌بندی خودکار: اگر شما یک بازه طولانی از داده‌ها را جستجو کنید، API فقط صفحه اول نتایج را تا حداکثر اندازه صفحه برای آن نقطه پایانی، همراه با nextPageToken برمی‌گرداند. برای درخواست صفحات بعدی باید از nextPageToken استفاده کنید.
  • اندازه‌های متغیر صفحه: محدودیت‌های محدودیت به نقطه پایانی و نوع داده بستگی دارد. برای اکثر انواع داده، اندازه صفحه حداکثر 10000 است. با این حال، برای انواع داده خاصی مانند exercise و sleep ، اندازه پیش‌فرض و حداکثر صفحه 25 است. به عنوان مثال، اگر یک کلاینت تمام داده‌های خواب را برای 10 سال گذشته درخواست کند، API همچنان فقط 25 جلسه خواب را در صفحه اول برمی‌گرداند.
  • محدودیت‌های محدوده تاریخ جمع‌بندی: برای نقاط پایانی جمع‌بندی و تجمیع داده‌ها (مانند rollUp و dailyRollUp )، محدوده‌های تاریخ پرس‌وجو بر اساس نوع داده محدود می‌شوند:
    • حداکثر بازه زمانی ۱۴ روز برای calories-in-heart-rate-zone ، heart-rate ، active-minutes و total-calories .
    • حداکثر بازه زمانی ۹۰ روز برای سایر انواع داده‌های rollup.

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

برای اطمینان از عملکرد بهینه و جلوگیری از خطاهای API، هنگام جستجوی داده‌های تاریخی، این دستورالعمل‌ها را دنبال کنید:

همگام‌سازی مرحله‌ای داده‌ها (بار گرم در مقابل بار سرد)

  • بارگذاری "داغ" اولیه: در طول توالی بارگذاری اولیه، فقط داده‌های ۷ تا ۱۴ روز اخیر را دریافت و رندر کنید. این تضمین می‌کند که کاربران داده‌ها را فوراً و بدون انتظار برای کوئری‌های طولانی مدت مشاهده می‌کنند.
  • بارگذاری «سرد» پس‌زمینه: بازیابی داده‌های قدیمی‌تر را پس از رندر شدن رابط کاربری اصلی، به یک صف ناهمزمان و با اولویت پایین‌تر یا فرآیند پس‌زمینه واگذار کنید.

قطعه‌بندی پرس‌وجو برای تجمیع

  • از آنجا که نقاط پایانی rollup و daily rollup حداکثر محدوده تاریخ (۱۴ یا ۹۰ روز بسته به نوع داده) را اعمال می‌کنند، شما باید پرس‌وجوهای تجمیع تاریخی بزرگ را به فواصل زمانی کوچک‌تر و متوالی در این محدوده‌ها تقسیم کنید.
  • این زیرپرس‌وجوها را با خیال راحت دسته‌بندی یا مرتب کنید تا محدودیت‌های همزمانی رعایت شود و شاخص‌های پیشرفت رابط کاربری ثابتی حفظ شوند.

از رول‌آپ‌های از پیش تجمیع‌شده استفاده کنید

داشبوردهای نمای کلی و نمودارهای روند را برای استفاده از نقاط پایانی از پیش تجمیع‌شده و خلاصه (مانند DailyRollUpDataPoints ) بازسازی کنید. این کار به طور چشمگیری سربار محاسباتی در backend و زمان انتقال شبکه به کلاینت را کاهش می‌دهد.

مدیریت خطای انعطاف‌پذیر (تلاش‌های مجدد هوشمند)

  • هنگام مواجهه با محدودیت‌های نرخ ( 429 Too Many Requests ) و زمان‌های وقفه دروازه سرور ( 504 Gateway Timeout ) ، مدیریت دقیق بازگشت نمایی را پیاده‌سازی کنید. هرگز بلافاصله بارهای بزرگ و ناموفق را دوباره امتحان نکنید. تلاش‌های مجدد فوری، ازدحام backend را چند برابر کرده و باعث تخریب سیستم می‌شوند.