راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
تحويل طابع زمني بتوقيت UTC إلى الوقت المحلي لمستخدميك
تخزين الطوابع الزمنية بتوقيت UTC هو القرار الصحيح لقاعدة البيانات. أما عرض توقيت UTC للمستخدم في تذكرة دعم أو تأكيد طلب أو سجل نشاط فليس كذلك، وهو من الإزعاجات الصغيرة الأكثر شيوعًا في واجهة أي منتج.
التحويل في خطوتين
أولًا، اعرف المكان الذي يجب تفسير الطابع الزمني وفقه، إما إحداثيات عنوان مسجّل لديك أو إحداثيات من استعلام IP. ثانيًا، مرّر هذه الإحداثيات والطابع الزمني بتوقيت UTC نفسه إلى /v1/timezone باستخدام المعامل time، بحيث يطابق فرق التوقيت المُعاد اللحظة المعنية لا اللحظة الحالية.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-05:00",
"abbreviation": "EST"
}طبّق قيمة utc_offset على الطابع الزمني المخزّن بتوقيت UTC، أو مرّر معرّف المنطقة الزمنية إلى شيفرة تنسيق التاريخ الخاصة بك، واعرض النتيجة بدلًا من قيمة UTC الخام.
مثال ثانٍ بفارق عدة أشهر
تعيد الإحداثيات نفسها فرق توقيت مختلفًا بحسب الطابع الزمني الذي تمرّره، وهذا هو سبب وجود المعامل time أصلًا.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-04:00",
"abbreviation": "EDT"
}لاحظ أن فرق التوقيت تغيّر من سالب خمس ساعات إلى سالب أربع ساعات بين الاستدعاءين للموقع نفسه تمامًا، لمجرد أن أحد الطابعين الزمنيين يقع ضمن التوقيت الصيفي والآخر لا يقع. والعرض الذي يتجاهل ذلك ويطبّق فرق توقيت ثابتًا واحدًا على الاثنين سيكون مخطئًا بساعة في أحدهما.
لماذا يهم المعامل time
يتغيّر فرق التوقيت على مدار السنة في معظم الأماكن التي تطبّق التوقيت الصيفي. إذا كنت تستدعي نقطة النهاية دائمًا دون المعامل time، فستحصل على فرق التوقيت الحالي، وهو سيكون خاطئًا لطابع زمني يعود إلى ستة أشهر مضت. مرّر دائمًا الطابع الزمني الذي تحوّله، لا الوقت الحالي، عندما يُحتمل أن يقع الاثنان على جانبين متقابلين من تغيير التوقيت الصيفي.
خزّن المنطقة الزمنية مؤقتًا، لا فرق التوقيت
نادرًا ما يتغير معرّف المنطقة الزمنية لمجموعة إحداثيات معينة، لذا من الآمن تخزين سلسلة timezone نفسها مؤقتًا مقرونة بالموقع. أما قيمتا utc_offset وabbreviation فليس من الآمن تخزينهما مؤقتًا لمدة طويلة، لأنهما تتغيران مع التوقيت الصيفي، لذا أعد حسابهما وقت العرض بدلًا من تخزينهما.
حالة حدّية تستحق المعرفة
لا تطبّق كل المواقع التوقيت الصيفي أصلًا. فالموقع الذي يبقى على فرق توقيت ثابت طوال العام سيعيد قيمة utc_offset نفسها أيًا كان الطابع الزمني الذي تمرّره، وهذا سلوك متوقع وليس علامة على تجاهل المعامل time. لا تفترض أن النتيجة الثابتة عبر طابعين زمنيين مختلفين تعني وجود عطل.
تكلفة الطلبات
كل تحويل يُحتسب طلبًا واحدًا. ولوحة التحكم التي تحوّل الأوقات لسجلات مخزنة كثيرة دفعة واحدة يجب أن ترسل الإحداثيات الأساسية على دفعات عبر طلب POST مجمّع بدلًا من المرور على الطوابع الزمنية واحدًا تلو الآخر، مع الحفاظ على تكلفة طلب واحد لكل عنصر ولكن في استدعاء واحد.
ضبط الوقت المحلي بشكل صحيح أهم مما تتوقعه معظم الفرق، إلى أن تُظهر تذكرة دعم الساعة الخاطئة. تفاصيل حقول الطلب والاستجابة متوفرة في توثيق الاستعلام عن المنطقة الزمنية.