معايير البروتوكول

تتّبع واجهة برمجة التطبيقات مجموعة من معايير HTTP API وتتيح idempoency لتسهيل عملية التكامل.

عناوين URL التي تستضيفها Google

توفر المستندات الخاصة بكل طريقة تستضيفها Google عنوان URL أساسيًا، اسم الطريقة ورقم الإصدار الرئيسي. إنشاء عنوان URL الكامل عن طريق إضافة رقم تعريف حساب شركة تكامل الدفع الخاص بالمتصل إلى النهاية. على سبيل المثال، المستندات المتعلقة بطريقة الارتداد التي تستضيفها Google يحدد عنوان URL:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

إذا كان رقم تعريف حساب جهة تكامل الدفعات الخاص بالمتصل هو INTEGRATOR_1، سيضيف الطلب. إلى نهاية عنوان URL لتشكيل:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

ملاحظة: صفحة وثائق نقطة النهاية للطريقة المحددة التي تستخدمها الذي يؤدي تنفيذه إلى عنوان URL الأكثر دقةً لطلبك.

عناوين URL التي يستضيفها الشركاء

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

بيئات وضع الحماية والإنتاج

تستضيف Google واجهات برمجة التطبيقات للدفعات العادية في كل من وضع الحماية (للتطوير الاختبار) والإنتاج. الطلبات في بيئة وضع الحماية من Google لا تسبب أي مسؤولية مالية في العالم الحقيقي. يوفر وضع الحماية بيئات الإنتاج منفصلة تمامًا ولا تشارك المفاتيح أو معلومات المعاملة.

تتوقع Google أن يكون وضع الحماية الخاص بك متاحًا بشكل مستمر نظرًا لأننا سنستخدم وضع الحماية لاختبار التغييرات الأولى والميزات الجديدة.

المسار الأساسي لوضع الحماية من Google

https://vgw.sandbox.google.com/secure-serving/gsp/

ملاحظة: إذا سبق أن بدأت عملية الدمج واستدعيت مضيف https://billpaynotification.sandbox.googleapis.com، يمكنك المتابعة إلى القيام بذلك. يجب أن تستدعي عمليات الدمج الجديدة "vgw.sandbox.google.com" المضيف.

المسار الأساسي لإنتاج Google

https://vgw.googleapis.com/secure-serving/gsp/

ملاحظة: إذا سبق أن بدأت عملية الدمج واستدعيت https://billpaynotification.googleapis.com، يمكنك الاستمرار في ذلك. يجب أن تستدعي عمليات الدمج الجديدة "vgw.googleapis.com" المضيف.

سيستخدم هذا الدليل نقاط نهاية الإنتاج.

نوع المحتوى والترميز

يجب أن تستخدم حمولات الرسائل التي تستخدم تشفير PGP نوع المحتوى application/octet-stream; charset=utf-8 يجب أن تكون نصوص طلبات PGP باستخدام ترميز base64url، على النحو المحدد في الفقرة 5 من نموذج RFC4648. حمولات الرسائل التي تستخدم تشفير JWE يجب أن تستخدم نوع المحتوى application/jose; charset=utf-8 خيار التسلسل المكثف يعتمده JWE/JWS في التعامل مع ترميز نص الطلب النهائي.

رموز حالة HTTP

صُممت واجهات برمجة التطبيقات في Google Payments API لعرض رمز حالة HTTP 200. لجميع الطلبات التي يمكن للخادم معالجتها. ويتضمن ذلك كلاً من الطلبات الناجحة والمرفوضة من منظور الشركة أو ومنطق التطبيق. ينبغي ألا تؤدي الطلبات التي لا يمكن معالجتها إلى رمز حالة HTTP 200 لأنّها تمثل خطأ بين Google شريك. بدلاً من ذلك، يجب أن تستخدم استجابة واجهة برمجة التطبيقات حالة HTTP المناسبة الرموز أدناه مع كائن ErrorResponse اختياري.

أخطاء HTTP وأسبابه
400	BAD REQUEST حدّد العميل وسيطة غير صالحة. يمكن أيضًا إرجاع هذه العملية إذا تم رفض العملية لأن النظام ليست في الحالة المطلوبة لتنفيذ العملية. يمكنك استخدام هذا الخيار في حال تعذّر إتمام محاولات إعادة محاولة الطلب إلى أن تظهر حالة النظام. بشكل صريح. على سبيل المثال، إذا تعذّر طلب استرداد الأموال بسبب يشير إلى تسجيل غير موجود، لن تنجح إعادة المحاولة إلى أن يبقى الالتقاط في نظام الدمج. ملاحظة: يجب عدم استخدام BAD_REQUEST (400) الحالات التي يظهر فيها خطأ مناسب في التطبيق. بالنسبة على سبيل المثال، يجب عرض العملات غير الصحيحة ACCOUNT_DOES_NOT_SUPPORT_CURRENCY عند استخدام الرمز 200 إذا كانت تحتوي استجابة عادية على هذا الحقل أو التعداد.
401	UNAUTHORIZED لا يتضمن الطلب بيانات اعتماد مصادقة صالحة العملية. على سبيل المثال، يجب أن تكون التوقيعات غير الصالحة أو التوقيعات غير المعروفة إرجاع 401.
403	FORBIDDEN / PERMISSION DENIED لا يملك المتصل إذنًا لتنفيذ العملية المحددة.
404	NOT FOUND تعذّر العثور على كيان مطلوب، مثل دفعة أو مستخدم.
409	CONFLICT / ABORTED تم إلغاء العملية، عادةً بسبب مشكلة تتعلق بالتزامن مثل حالات تعذُّر فحص جهاز التسلسل وعمليات إلغاء المعاملات وما إلى ذلك
412	PRECONDITION FAILED يجب استخدام هذا الرمز في الحالات التي يتم فيها استخدام مفتاح تحديد الهوية وأعيد استخدامها بمعلمات مختلفة.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS تم استنفاد بعض موارد النظام.
499	CANCELLED تم إلغاء العملية (عادةً من قِبل المتصل).
500	INTERNAL ERROR أخطاء داخلية. يعني ذلك أنّ بعض القيم المتغيرة المتوقعة من خلال النظام الأساسي تم عطل.
501	UNIMPLEMENTED لم يتم تنفيذ العملية أو دعمها أو تفعيلها في هذه الخدمة.
503	UNAVAILABLE هذه الخدمة غير متاحة حاليًا. هذه مرحلة عابرة على الأرجح الحالة ويمكن تصحيحها من خلال إعادة المحاولة.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED انتهت صلاحية الموعد النهائي قبل اكتمال العملية. بالنسبة للعمليات التي تغير حالة النظام، فقد يظهر هذا الخطأ حتى إذا اكتملت العملية بنجاح. على سبيل المثال، قد يكون الرد الناجح من الخادم قد يتأخر لمدة طويلة بما يكفي للموعد النهائي تنتهي صلاحيته.

مدى تكرار الطلب

إنّ تحديد هوية الطلب هو استراتيجية مركزية تُستخدَم في خطة "الدفعات العادية" واجهات برمجة التطبيقات المستخدمة لضمان أن تكون تفاعلات النظام بين Google والشركاء بالقوة وتقبّل الأخطاء. الطلبات الهوية هي الطلبات التي يمكن يمكن إرسالها عدة مرات ولكن يكون لها نفس تأثير طلب واحد. تسهل هذه الإستراتيجية الاتساق النهائي بين الأنظمة من خلال إعادة المحاولة بشكل آمن، ما يسمح لأنظمتنا بالانسجام مع الاتفاق على حالة المورد.

تستفيد واجهة برمجة التطبيقات لدينا من الفعالية لتحقيق ما يلي:

• وتقليل مشكلات التسوية عن طريق تسهيل تتبع جميع الإجراءات قابل للتدقيق.
• تمنع شروط السباق من خلال التأكد من أن الطلبات المتعددة المتطابقة من العميل نفسه لا يؤدي إلى حالة نهائية مختلفة.
• وتقليل الحالة عبر السماح بفهم الطلبات بمعزل عن بعضها، لتحسين الأداء وإنتاجية البيانات عن طريق إزالة العبء على الخادم الناتج عن الاحتفاظ بالبيانات.
• تجنب الحاجة إلى حقول إضافية للإشارة إلى ما إذا كان الطلب عبارة عن إعادة محاولة

ملاحظة: يجب عدم تخزين نتائج الأخطاء مؤقتًا أو عرضها تلقائيًا. و، لإعادة المحاولة المبرمَجة بحثًا عن الأخطاء، يجب أن تستخدم استراتيجية خوارزمية تراجع كسرية.

أمثلة

المثال 1: فقدان الاتصال قبل تلقّي الردّ

السيناريو:

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

النتيجة:

وفي هذه الحالة، يجب أن يرد خادم الدمج بالردّ نفسه الوارد في الخطوة رقم 2 بما أنّ جميع المَعلمات هي نفسها باستثناء responseTimestamp. يحدث الأثر الجانبي مرة واحدة فقط، في الخطوة 2. الخطوة 4 ليس لها أي أثر جانبي.

المثال 2: طلب تم إرساله إلى خادم يخضع للصيانة

السيناريو:

1. قاعدة بيانات خادم أداة الدمج معطلة لأسباب تتعلق بالصيانة.
2. وترسل Google طلبًا إلى شركة الدمج.
3. تعرض عملية الدمج رمز الحالة UNAVAILABLE بشكل صحيح.
4. يتلقى خادم Google الرد ويحدد موعدًا لإعادة المحاولة.
5. تعود قاعدة بيانات خادم أداة الدمج إلى الإنترنت مرة أخرى.
6. تُعيد Google إرسال الطلب من خلال الخطوة 2 (رقم تعريف الطلب نفسه وتفاصيل الطلب). ولكن تم تحديثه في requestTimestamp). يُرجى العلم أنّ أرقام تعريف الطلبات لكلا الطلبَين هي نفسها.
7. يتلقّى خادم عملية الدمج الطلب ويعرض رمز الحالة "حسنًا" مع برد كامل.

النتيجة:

وفي هذه الحالة، يجب أن يعالج خادم الدمج الطلب في الخطوة رقم 7 وليس تعرض HTTP 503 (UNAVAILABLE). بدلاً من ذلك، يجب أن يلتزم خادم عملية الدمج معالجة الطلب وعرض الرسالة "موافق" باستخدام الرسائل المناسبة. لاحظ أنه في حين أن النظام هو UNAVAILABLE. يجوز لـ Google تقديم طلبات متكررة مشابهة الخطوة رقم 2. من المفترض أن يؤدي كل طلب إلى رسالة مشابهة للخطوة رقم 3. في النهاية، ستحدث الخطوة رقم 6 والخطوة رقم 7.

المثال 3: لا تتطابق الرسالة التي تمت إعادة توجيهها مع الرسالة الأولية بسبب خطأ في الاسترداد

السيناريو:

1. وترسل Google طلبًا إلى شركة الدمج.
2. ويتلقّى خادم عملية الدمج هذا الطلب ويعالجه بنجاح.
3. يفقد خادم Google الطاقة قبل تلقي الاستجابة في الخطوة رقم 2.
4. تتم استعادة طاقة خادم Google ويحاول إرسال الطلب نفسه ولكن لسوء الحظ بعض المعاملات مختلفة.

النتيجة:

في هذه الحالة، يجب أن يردّ خادم الدمج باستخدام HTTP 412. (PRECONDITION FAILED) الذي يوضّح لـ Google أنّ هناك حدوث خطأ في هذا النظام.