البدء

حدود المعدّل والحصص

حصص المفاتيح، والحدود لكل عنوان IP، ومُقيِّد الطلبات، والمفاتيح غير المحدودة، ومستويات الخطط، وكيفية سلوك التقييد.

حدود المعدّل والحصص

تطبّق Navvo ثلاثة أنواع من الحدود للحفاظ على سرعة المنصة وعدالتها:

حصّة المفتاح: عدد الطلبات التي يحقّ لكل مفتاح API إرسالها في الدقيقة وفي اليوم.
الحدّ لكل عنوان IP: عدد الطلبات المرسَلة بمفتاح التي يمكن أن تأتي من عنوان IP واحد للعميل في الدقيقة وفي اليوم.
مُقيِّد الطلبات: عدد الطلبات التي يمكن أن يرسلها عنوان IP واحد للعميل إلى نقطة نهاية واحدة في الدقيقة، بمفتاح أو دونه.

جميع النوافذ ثابتة وليست متدحرجة. الدقيقة هي دقيقة الساعة: تبدأ عدّاداتها من جديد عند الثانية :00 من كل دقيقة. واليوم هو يوم بتوقيت UTC: تبدأ عدّاداته من جديد عند الساعة 00:00 بتوقيت UTC.

الحدود الافتراضية

الحدّ	الافتراضي	ينطبق على	عند التجاوز
حصّة المفتاح، في الدقيقة	حسب خطّة المفتاح: 60 طلبًا في خطّة `free`	كل مفتاح API (`quotaPerMinute`).	`403` `QUOTA_EXCEEDED`
حصّة المفتاح، في اليوم	حسب خطّة المفتاح: 5,000 طلب في خطّة `free`	كل مفتاح API (`quotaPerDay`).	`403` `QUOTA_EXCEEDED`
لكل IP، في الدقيقة	90 طلبًا، أو حصّة الدقيقة الخاصة بالمفتاح إن كانت أعلى	الطلبات المرسَلة بمفتاح من عنوان IP واحد إلى نقاط نهاية تتطلّب نطاقًا.	`403` `QUOTA_EXCEEDED`
لكل IP، في اليوم	30,000 طلب، أو حصّة اليوم الخاصة بالمفتاح إن كانت أعلى	الطلبات المرسَلة بمفتاح من عنوان IP واحد إلى نقاط نهاية تتطلّب نطاقًا.	`403` `QUOTA_EXCEEDED`
مُقيِّد الطلبات	3,000 طلب في الدقيقة	عنوان IP واحد على نقطة نهاية واحدة، بمفتاح أو دونه.	`429` `RATE_LIMITED`

لكل مفتاح حصّته الخاصة في الدقيقة وفي اليوم. يأخذ المفتاح الجديد حدود خطّته ما لم تضبط quotaPerMinute / quotaPerDay بنفسك: تمنح free ‏60 طلبًا في الدقيقة و5,000 في اليوم، وstarter ‏255 و100,000، وتمنح growth وscale وenterprise ‏255 في الدقيقة مع 1,000,000 و8,000,000 و10,000,000 في اليوم. وفي بوابة المطوّرين وواجهة المطوّرين البرمجية يمكنك ضبط ما يصل إلى 255 طلبًا في الدقيقة و10,000,000 طلب في اليوم: وهذا هو سقف الخدمة الذاتية. أما المفاتيح التي تُعِدّها Navvo فيمكن أن تكون حدودها أعلى، أو أن تكون غير محدودة.

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

الحدود لكل عنوان IP

ينطبق الحدّ لكل عنوان IP فقط على الطلبات التي ترسل مفتاح API إلى نقطة نهاية تتطلّب نطاقًا. تعدّ Navvo هذه الطلبات لكل عنوان IP للعميل، عبر كل المفاتيح المستخدمة من ذلك العنوان. ويُقارَن كل طلب بحدّ المنصة (90 في الدقيقة و30,000 في اليوم) أو بحصّة المفتاح المُرسِل نفسه، أيّهما أعلى. وبذلك لا يُقيَّد المفتاح الوحيد المستخدم من عنوانه أبدًا بأقلّ من حصّته. أما إذا أرسلت عدّة مفاتيح من عنوان واحد فإنها تتقاسم عدّادًا واحدًا، فقد تبلغ حركتها مجتمعةً الحدّ لكل عنوان IP قبل أن يبلغ كل مفتاح حصّته: أرسل كل مفتاح من عنوانه الخاص، أو استخدم مفتاحًا واحدًا بحصّة تغطّي الحركة كلها. أما طلبات المفتاح غير المحدود فلا تُعَدّ ولا تُفحَص.

لا تخضع الطلبات المرسَلة دون مفتاح للحدّ لكل عنوان IP، بل يغطّيها مُقيِّد الطلبات.

مُقيِّد الطلبات

تسمح كل نقطة نهاية لكل عنوان IP للعميل بما يصل إلى 3,000 طلب في الدقيقة، بمفتاح أو دونه. وتضع بعض نقاط النهاية حدًّا أضيق خاصًّا بها: فمثلًا تسمح عمليتا البحث عن أقرب صورة شارع وعن تسلسل الصور بـ 60 طلبًا في الدقيقة، وتسمح أحداث البحث بـ 60 طلبًا في الدقيقة. وهناك بضع طبقات من بلاطات الخريطة تجلبها الخريطة المتحرّكة على دفعات، وهي لا تُقيَّد أبدًا، حتى لا تُرفَض خريطة أثناء رسمها.

عند تجاوز الحدّ، تجيب نقطة النهاية بالحالة 429 Too Many Requests مع code بقيمة RATE_LIMITED وترويسة Retry-After التي تذكر عدد الثواني الواجب انتظارها.

الخطط

تحمل المفاتيح مستوى خطّة يحدّد الحصّة المتاحة:

الخطّة	مخصّصة لـ
`free`	النماذج الأوّلية والتطبيقات منخفضة الحجم.
`starter`	المنتجات في مراحلها المبكّرة عند إطلاقها.
`growth`	أعباء الإنتاج عالية الحجم.
`scale`	حركة المرور الإنتاجية واسعة النطاق.
`enterprise`	حدود مخصّصة ودعم مكرّس.

مفاتيح الخطط هي free وstarter وgrowth وscale وenterprise (القيمة القديمة startup أصبحت الآن تُقابِل starter). عند إنشاء أو تحديث مفتاح دون حصص صريحة، يتبنّى قيمتَي quotaPerMinute / quotaPerDay الافتراضيتين للخطة المطابقة. راجع فهرس الخطط للتسعير والطلبات المشمولة.

هل تحتاج إلى إنتاجية أعلى؟ اضبط quotaPerMinute / quotaPerDay عند إنشاء المفتاح، ضمن سقف الخدمة الذاتية (راجع المصادقة). ولأكثر من ذلك، تواصل مع Navvo بشأن خطّة growth/scale/enterprise، أو حدود أعلى، أو مفتاح غير محدود.

ترويسات الاستجابة

عندما يرسل طلبٌ مفتاحًا إلى نقطة نهاية تتطلّب نطاقًا، تبيّن الاستجابة موقف المفتاح من حصّته:

الترويسة	المعنى
`x-navvo-quota-limit-minute`	حصّة الدقيقة للمفتاح، أو `unlimited`.
`x-navvo-quota-remaining-minute`	الطلبات المتبقّية في هذه الدقيقة، أو `unlimited`.
`x-navvo-quota-limit-day`	حصّة اليوم للمفتاح، أو `unlimited`.
`x-navvo-quota-remaining-day`	الطلبات المتبقّية اليوم (بتوقيت UTC)، أو `unlimited`.
`x-navvo-quota-reset-minute`	الثواني المتبقّية حتى تبدأ نافذة الدقيقة من جديد.
`x-navvo-quota-unlimited`	`true`. تُرسَل فقط للمفتاح غير المحدود.

تصف هذه الترويسات حصّة المفتاح نفسه، لا الحدّ لكل عنوان IP.

وتبيّن استجابات نقاط النهاية المقيَّدة أيضًا موقف عنوان IP الخاص بك من مُقيِّد الطلبات على تلك النقطة:

الترويسة	المعنى
`X-RateLimit-Limit`	حدّ نقطة النهاية في الدقيقة (3,000 ما لم تضع النقطة حدًّا خاصًّا بها).
`X-RateLimit-Remaining`	الطلبات المتبقّية لعنوان IP الخاص بك على هذه النقطة في النافذة الحالية.
`X-RateLimit-Reset`	الثواني المتبقّية حتى تبدأ النافذة من جديد.
`Retry-After`	مع `429`، ومع `403` `QUOTA_EXCEEDED` لنافذة الدقيقة: الثواني الواجب انتظارها قبل إعادة المحاولة.

تستطيع شيفرة المتصفّح على أي موقع قراءة كل هذه الترويسات (راجع المواصفات ← المصادر المتعدّدة).

عند تجاوزك لحدّ ما

حصّة المفتاح أو الحدّ لكل عنوان IP: `403 QUOTA_EXCEEDED`

تُرفَض الطلبات التي تتجاوز حصّة مفتاح أو حدًّا لكل عنوان IP بالحالة HTTP 403 مع code بقيمة QUOTA_EXCEEDED. ويبيّن الكائن details الحدّ الذي جرى بلوغه:

{
  "statusCode": 403,
  "message": "API key quota exceeded for scope routing: 180/minute",
  "error": "Forbidden",
  "code": "QUOTA_EXCEEDED",
  "details": { "scope": "routing", "limit": 180, "window": "minute", "observed": 181, "retryAfterSeconds": 23 },
  "requestId": "847c7a9b-a7c8-4b61-b138-d4e6b585626a"
}

حقل `details`	المعنى
`scope`	نطاق نقطة النهاية التي استدعيتها. يُرسَل لحصص المفاتيح فقط.
`limit`	الحدّ الذي جرى بلوغه.
`window`	`minute` أو `day`.
`observed`	الطلبات المحتسبة في هذه النافذة، بما فيها هذا الطلب.
`retryAfterSeconds`	الثواني المتبقّية حتى تبدأ نافذة الدقيقة من جديد، وتُرسَل أيضًا في `Retry-After`. يُرسَل لنوافذ الدقيقة فقط: فنافذة اليوم تبدأ من جديد عند 00:00 بتوقيت UTC.

الرسائل الأربع التي قد تراها هي API key quota exceeded for scope …: …/minute وAPI key quota exceeded for scope …: …/day وIP rate limit exceeded: …/minute وIP daily quota exceeded: …/day. تفرّع بناءً على code وdetails، لا على نصّ الرسالة.

مُقيِّد الطلبات: `429 RATE_LIMITED`

تحصل الطلبات التي تتجاوز مُقيِّد الطلبات على HTTP 429 مع code بقيمة RATE_LIMITED. انتظر عدد الثواني المذكور في ترويسة Retry-After قبل أن ترسل إلى نقطة النهاية تلك مجدّدًا.

المفاتيح غير المحدودة

يمكن لـ Navvo أن تجعل مفتاحًا غير محدود، مثلًا لشريك ترسل خوادمه الطلبات نيابةً عن مستخدمين كثيرين. ولا يمكنك ضبط ذلك بنفسك، لا في البوابة ولا عبر الواجهة البرمجية: تواصل مع Navvo. يحمل المفتاح غير المحدود "unlimited": true في كائن المفتاح، وتظهر له شارة Unlimited في بوابة المطوّرين.

المفتاح غير المحدود لا يخضع لما يلي:

حصّته في الدقيقة وفي اليوم. تبقى quotaPerMinute وquotaPerDay محفوظتين دون أن تُفرَضا، وتعودان إلى التطبيق إذا ألغت Navvo عدم التحديد؛
الحدّان لكل عنوان IP في الدقيقة وفي اليوم. فطلباته لا تُحتسب ضمنهما ولا تُفحَص مقابلهما، ولذلك لا تستطيع أيضًا أن تدفع مفاتيح أخرى مستخدمة من العنوان نفسه إلى تجاوزهما؛
مُقيِّد الطلبات البالغ 3,000 طلب في الدقيقة، على نقاط النهاية التي تتطلّب نطاق مفتاح API ولا تضع حدًّا أضيق خاصًّا بها؛
حدّ الـ 60 طلبًا في الدقيقة الخاص بـ POST /search/events.

أما ما يلي فيبقى منطبقًا على المفتاح غير المحدود:

الإلغاء، والنطاقات، والمواقع وعناوين IP التي قُيِّد المفتاح بها؛
الحظر الذي تفرضه Navvo على عناوين IP بسبب إساءة الاستخدام؛
نقاط النهاية التي لها حدّ خاص بها لمنع إساءة الاستخدام، مثل عمليتَي البحث عن أقرب صورة شارع وعن تسلسل الصور (60 طلبًا في الدقيقة لكل عنوان IP)، ونقاط نهاية الذكاء الاصطناعي المساعدة (30 في الدقيقة)، والنماذج العامة؛
مُقيِّد الطلبات البالغ 3,000 في الدقيقة على نقاط النهاية التي لا تتطلّب نطاق مفتاح API، مثل تسجيل الدخول ونقاط نهاية الحساب والمساعد الذكي؛
حدود حجم الطلب، مثل عدد أزواج المصفوفة، و50 عنوانًا في الترميز الجغرافي بالجملة، وعدد محطّات التحسين، وأحجام الأجسام.

يرفع عدم التحديد السقوف التي تضعها Navvo لكل مفتاح ولكل عنوان، لكنه لا يرفع سعة الخدمة نفسها، لذا تحدّث مع Navvo قبل إرسال أحجام مرتفعة جدًّا بشكل متواصل.

كيف تُظهِر الاستجابات ذلك. على نقاط النهاية التي تتطلّب نطاقًا، تحمل كل استجابة:

x-navvo-quota-limit-minute: unlimited
x-navvo-quota-remaining-minute: unlimited
x-navvo-quota-limit-day: unlimited
x-navvo-quota-remaining-day: unlimited
x-navvo-quota-unlimited: true

ولا ترسل نقاط النهاية التي رُفع عنها مُقيِّد الطلبات أي ترويسات X-RateLimit-*. ولا يتلقّى المفتاح غير المحدود QUOTA_EXCEEDED أبدًا.

يبقى الاستخدام محتسبًا. تواصل مقاييس استخدام المفتاح في البوابة عدّ الطلبات في هذه الدقيقة واليوم، دون سقف. وتعيد GET /developer/api-keys/:id/usage القيمة "unlimited": true مع minute.limit وday.limit بقيمة null. ويبقى كل طلب مُقاسًا بوزنه ومُفوتَرًا كالمعتاد.

يستطيع كل من يملك مفتاحًا غير محدود استخدامه دون سقف، لذا يكلّف تسرّبه أكثر. اقصره على عناوين IP لخوادمك (restrictions.ips، راجع تقييد المفتاح)، وأبقِه خارج التطبيقات وصفحات الويب، ودوّره إن تسرّب.

عندما تجعل Navvo مفتاحًا غير محدود أو تعيد تحديده، يسري التغيير خلال دقيقة تقريبًا.

أفضل الممارسات

خزّن مؤقتًا بكثافة

نادرًا ما تتغيّر البلاطات والأنماط وتفاصيل الأماكن من دقيقة لأخرى. احترم ترويسات Cache-Control وخزّن الاستجابات مؤقتًا حيثما أمكن.

ادمج الطلبات حيثما أمكن

استخدم نقطة نهاية المصفوفة بدلًا من N استدعاء مسار منفصل، واطلب بيانات خريطة محدودة باستخدام bbox/تغطية البلاطات.

أبقِ المفاتيح على الخادم

مرّر الطلبات عبر خادمك الخلفي حيثما أمكن، حتى لا يتضاعف مفتاح مشترك واحد عبر عناوين IP متعدّدة للعملاء.

احترم Retry-After

عند 429، أو 403 QUOTA_EXCEEDED، انتظر المدة المذكورة في Retry-After (أو حتى 00:00 بتوقيت UTC لنافذة اليوم) بدلًا من إعادة المحاولة فورًا. فالطلبات المرفوضة بالرمز QUOTA_EXCEEDED تُحتسب أيضًا من حصّة المفتاح، وحلقة إعادة المحاولة السريعة على حدّ الدقيقة تستنفد حصّة اليوم.

تُحسَب الحصص لكل طلب، عبر جميع النطاقات التي استخدمها ذلك المفتاح ضمن النافذة. تُحسَب عمليات القراءة والكتابة كلتاهما.

كل مفتاح مُقدَّم يُحاسَب على نطاقاته وحصّته دائمًا. حتى في عمليات النشر التي يكون فيها فرض المفاتيح متساهلًا، إذا أرسلت فعلًا مفتاح API فيجب أن يحمل النطاق الذي تتطلّبه نقطة النهاية وأن يكون ضمن حصّته — فالمفتاح المحدود النطاق أو المستنفِد لحصّته يعيد 403 (API key missing required scopes / QUOTA_EXCEEDED) بدلًا من التراجع إلى الوصول المجهول. امنح كل مفتاح النطاقات التي يحتاجها بالضبط، فلا يستطيع أن يفعل بصمت أكثر ممّا هو مقصود.

المصادقة

كيفية الحصول على مفاتيح Navvo البرمجية واستخدامها، وما النطاقات التي تتحكّم بالوصول.

الأخطاء ورموز الحالة

رموز حالة HTTP، وأشكال استجابات الأخطاء، وغلاف توفّر المحرّك.