نقاط النهاية

تقدّم هذه الصفحة نظرة عامة على اصطلاحات REST API، بالإضافة إلى فهرس للمهام الشائعة في Google Health API وأمثلة على كل منها.

اصطلاحات REST API

تتّبع Google Health API معايير مقترحات تحسين واجهات برمجة التطبيقات (AIP) من Google، وتحديدًا 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 العادي.

التواريخ

تظهر جميع التواريخ في Google Health API بالتنسيق YYYY-MM-DD. تتيح Nutrition API معيار ISO-8601 لقيم التاريخ مع الشروط التالية:

  • سنة مكوّنة من 4 أرقام YYYY
  • قيم السنوات ضمن النطاق من 0000 إلى 9999
  • عدم فرض قيود تاريخ البدء التي يشير إليها معيار ISO-8601 أو أي حقبة أخرى

العناوين

يتطلّب تنفيذ نقاط نهاية Google Health API استخدام العناوين المناسبة ورمز الدخول. يُنصح باستخدام العنوان التالي لكل من طلبات GET وPOST:

Authorization: Bearer access-token
Accept: application/json

فهرس مهام واجهة برمجة التطبيقات

يقدّم هذا القسم فهرسًا للمهام الشائعة في Google Health API وأمثلة على كل منها.

الحصول على رقم تعريف مستخدم Fitbit أو Google

بعد أن يوافق المستخدم من خلال Google OAuth 2.0، لا يحتوي ردّ الرمز المميّز على رقم تعريف مستخدم Fitbit أو Google. للحصول على رقم تعريف المستخدم، اطلب نقطة النهاية getIdentity. تعرض getIdentity كلاً من رقم تعريف مستخدم Fitbit القديم ورقم تعريف مستخدم Google.

ننصحك بطلب نقطة النهاية getIdentity وتخزين رقمَي تعريف المستخدمَين فور موافقة مستخدم جديد من خلال OAuth. يوفّر ذلك التوافق مع الإصدارات السابقة والإصدارات اللاحقة في عملية التكامل.

على سبيل المثال:

طلب

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 المتوافقة:

Option الوصف
users/me/dataSourceFamilies/all-sources القيمة التلقائية. تشمل البيانات من جميع مصادر البيانات المتاحة.
users/me/dataSourceFamilies/google-wearables تشمل البيانات من أجهزة التتبُّع من Google وFitbit (مثل أجهزة تتبُّع Fitbit وPixel Watch). ولا تشمل البيانات التي تم تسجيلها يدويًا.
users/me/dataSourceFamilies/google-sources تشمل بيانات المستخدم على Google الخاصة بالطرف الأول، مثل البيانات من أجهزة التتبُّع والبيانات التي تم تسجيلها يدويًا.

في ما يلي مثال على فلترة بيانات النوم التي سجّلها جهاز التتبُّع فقط في اليوم التالي لتاريخ 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 استنادًا إلى الوقت الفعلي للمستخدم (بتوقيت غرينتش).

عند طلب نقطة النهاية 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". تبلغ قراءة نسبة الدهون بالجسم الجديدة للمستخدم 20% لتاريخ 2026-03-10.

طلب

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 إلى نقطة النهاية dataPoints في nutrition-log. يحتوي نص الطلب على DataPoint مع كائن nutritionLog. لمزيد من المعلومات، اطّلِع على دليل التغذية.

على سبيل المثال:

طلب

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"
      ]
    }
  ]
}

الاستعلام عن البيانات السابقة

من بين المزايا الأساسية في Google Health API إمكانية تتبُّع أداء المستخدم ومراقبة مؤشراته الصحية على مدى فترات زمنية طويلة. يمكنك الاستعلام عن بيانات المستخدم منذ تاريخ تسجيلها، ولا تفرض واجهة برمجة التطبيقات أي قيود على مقدار البيانات السابقة التي يمكن أن يستهلكها تطبيقك.

ومع ذلك، لا يزال الاستعلام عن البيانات السابقة يخضع لحدود المعدّل العادية . لإدارة استقرار النظام ومنع الحمولات الزائدة، تستخدِم Google Health API التقسيم التلقائي على عدّة صفحات بأحجام صفحات خاصة بنقطة النهاية. يُرجى ملاحظة الحدود والسلوكيات التالية:

  • التقسيم التلقائي على عدّة صفحات: إذا استعلمت عن فترة طويلة من البيانات، لن تعرض واجهة برمجة التطبيقات سوى الصفحة الأولى من النتائج بحد أقصى لحجم الصفحة لنقطة النهاية هذه، بالإضافة إلى nextPageToken. يجب استخدام nextPageToken لطلب الصفحات اللاحقة.
  • أحجام الصفحات المتغيّرة: تعتمد الحدود القصوى على نقطة النهاية ونوع البيانات. بالنسبة إلى معظم أنواع البيانات، يبلغ الحد الأقصى لأحجام الصفحات 10,000. ومع ذلك، بالنسبة إلى أنواع بيانات معيّنة، مثل exercise وsleep، يبلغ الحد الأقصى لحجم الصفحة التلقائي والأقصى 25. على سبيل المثال، إذا طلب أحد العملاء جميع بيانات النوم خلال السنوات العشر الماضية، ستعرض واجهة برمجة التطبيقات 25 جلسة نوم فقط في الصفحة الأولى.
  • قيود النطاق الزمني للتجميع: بالنسبة إلى نقاط نهاية تجميع البيانات (مثل rollUp وdailyRollUp)، يتم تقييد النطاقات الزمنية لطلبات البحث استنادًا إلى نوع البيانات:
    • نطاق أقصاه 14 يومًا لكل من calories-in-heart-rate-zone و heart-rate وactive-minutes وtotal-calories.
    • نطاق أقصاه 90 يومًا لجميع أنواع بيانات التجميع الأخرى.

اعتمادًا على حجم البيانات السابقة التي يحتاجها تطبيقك، سيتطلّب استرداد مجموعة البيانات بأكملها الانتقال إلى الصفحات بالتسلسل. ضَع ذلك في الاعتبار عند تصميم عملية مزامنة بيانات تطبيقك.

لضمان الأداء الأمثل وتجنُّب أخطاء واجهة برمجة التطبيقات، اتّبِع هذه الإرشادات عند الاستعلام عن البيانات السابقة:

مزامنة البيانات على مراحل (التحميل السريع مقابل التحميل البطيء)

  • التحميل "السريع" الأولي: يمكنك جلب وعرض آخر 7 إلى 14 يومًا فقط من البيانات أثناء تسلسل التحميل الأساسي. يضمن ذلك ظهور البيانات للمستخدمين على الفور بدون انتظار طلبات البحث الطويلة.
  • التحميل "البطيء" في الخلفية: يمكنك تفويض استرداد البيانات السابقة إلى قائمة انتظار غير متزامنة ذات أولوية أقل أو عملية في الخلفية بعد عرض واجهة المستخدم الأساسية.

تقسيم طلبات البحث للتجميع

  • بما أنّ نقاط نهاية التجميع والتجميع اليومي تفرض حدًا أقصى للنطاق الزمني (14 أو 90 يومًا حسب نوع البيانات)، يجب تقسيم طلبات البحث الكبيرة لتجميع البيانات السابقة إلى فواصل زمنية أصغر ومتسلسلة ضمن هذه الحدود.
  • يمكنك تجميع طلبات البحث الفرعية هذه أو تسلسلها بأمان للالتزام بحدود التزامن والحفاظ على مؤشرات تقدّم واجهة المستخدم الثابتة.

الاستفادة من عمليات التجميع المسبقة

يمكنك إعادة هيكلة لوحات البيانات العامة ومخططات المؤشرات لاستخدام نقاط نهاية ملخّص مجمّعة مسبقًا (مثل DailyRollUpDataPoints). سيؤدي ذلك إلى تقليل كبير في حمل الحوسبة على الواجهة الخلفية ووقت نقل الشبكة إلى العميل.

معالجة الأخطاء المرنة (عمليات إعادة المحاولة الذكية)

  • يمكنك تنفيذ معالجة صارمة للتراجع الأسي عند مواجهة حدود المعدّل (429 Too Many Requests) ومهلات بوابة الخادم (504 Gateway Timeout). لا تعِد أبدًا محاولة إرسال الحمولة الكبيرة التي تعذّر إرسالها على الفور. تؤدي عمليات إعادة المحاولة الفورية إلى زيادة الازدحام في الواجهة الخلفية وتفاقم تدهور النظام.