استانداردهای پروتکل، استانداردهای پروتکل

API از مجموعه ای از استانداردهای HTTP API پیروی می کند و از idempotency برای تسهیل یکپارچگی قوی تر پشتیبانی می کند.

URL های میزبانی شده توسط گوگل

اسناد مربوط به هر روش میزبانی شده توسط Google یک URL پایه را ارائه می دهد که شامل نام روش و شماره نسخه اصلی است. URL کامل با افزودن شناسه حساب یکپارچه کننده پرداخت تماس گیرنده به انتها ایجاد می شود. به عنوان مثال، اسناد روش echo میزبانی شده توسط 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 های میزبانی شریک

اسناد مربوط به هر روش API میزبان شریک یک URL پایه را ارائه می دهد که شامل نام روش و شماره نسخه اصلی است. شما نباید شناسه حساب یکپارچه‌ساز پرداخت ( PIAID ) را در URLهایی که میزبانی می‌کنید قرار دهید.

Sandbox و محیط های تولید

Google APIهای Standard Payments را هم در جعبه ایمنی (برای اهداف توسعه و آزمایش) و هم در تولید میزبانی می‌کند. درخواست‌ها در محیط سندباکس Google هیچ گونه تعهد مالی در دنیای واقعی ایجاد نمی‌کنند. Sandbox و محیط های تولید کاملاً مجزا هستند و کلیدها یا اطلاعات تراکنش را به اشتراک نمی گذارند.

Google انتظار دارد که جعبه ایمنی شما به طور مداوم در دسترس باشد زیرا ما از جعبه ایمنی برای اولین بار آزمایش تغییرات و ویژگی‌های جدید استفاده می‌کنیم.

مسیر پایه سندباکس گوگل

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

مسیر پایه تولید گوگل

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

این راهنما از نقاط پایانی تولید استفاده خواهد کرد.

نوع محتوا و کدگذاری

محموله‌های پیامی که از رمزگذاری PGP استفاده می‌کنند باید از نوع محتوا application/octet-stream; charset=utf-8 . بدنه های درخواست PGP باید با استفاده از رمزگذاری base64url ارسال شوند، همانطور که در rfc4648 §5 تعریف شده است.محموله‌های پیامی که از رمزگذاری JWE استفاده می‌کنند باید از نوع محتوا application/jose; charset=utf-8 . گزینه Compact Serialization که توسط JWE/JWS پشتیبانی می شود، کدگذاری بدنه درخواست نهایی را کنترل می کند.

کدهای وضعیت HTTP

APIهای پرداخت استاندارد برای بازگرداندن کد وضعیت HTTP 200 برای همه درخواست‌هایی که می‌توانند توسط سرور پردازش شوند، طراحی شده‌اند. این شامل درخواست های موفق و رد شده از منظر منطق تجاری یا برنامه است. درخواست‌هایی که پردازش نمی‌شوند نباید منجر به کد وضعیت HTTP 200 شوند زیرا نشان‌دهنده یک خطا بین Google و شریک هستند. در عوض، پاسخ API باید از کدهای وضعیت HTTP مناسب زیر با یک شیء اختیاری ErrorResponse استفاده کند.

خطاها و دلایل HTTP
400 BAD REQUEST

کلاینت آرگومان نامعتبری را مشخص کرده است.

همچنین در صورتی که عملیات رد شده باشد، می توان آن را برگرداند زیرا سیستم در وضعیت مورد نیاز برای اجرای عملیات قرار ندارد.

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

401 UNAUTHORIZED

درخواست دارای اعتبار احراز هویت معتبر برای عملیات نیست. برای مثال، امضاهای نامعتبر یا امضاهای ناشناخته باید 401 را برگردانند.

403 FORBIDDEN / PERMISSION DENIED

تماس گیرنده اجازه اجرای عملیات مشخص شده را ندارد.

404 NOT FOUND

برخی از نهادهای درخواستی مانند پرداخت یا کاربر یافت نشد.

409 CONFLICT / ABORTED

این عملیات معمولاً به دلیل یک مشکل همزمانی مانند خرابی‌های بررسی ترتیب‌دهنده، لغو تراکنش و غیره متوقف شد.

412 PRECONDITION FAILED

این کد باید در شرایطی استفاده شود که یک کلید idempotency با پارامترهای مختلف دوباره استفاده می شود.

429 RESOURCE EXHAUSTED / TOO MANY REQUESTS

برخی از منابع سیستم تمام شده است.

499 CANCELLED

عملیات لغو شد (معمولاً توسط تماس گیرنده).

500 INTERNAL ERROR

خطاهای داخلی این بدان معنی است که برخی از متغیرهای مورد انتظار سیستم زیربنایی شکسته شده است.

501 UNIMPLEMENTED

عملیات در این سرویس اجرا، پشتیبانی یا فعال نشده است.

503 UNAVAILABLE

این سرویس در حال حاضر در دسترس نیست. این یک وضعیت گذرا است و ممکن است با تلاش مجدد اصلاح شود.

504 GATEWAY TIMEOUT / DEADLINE EXCEEDED

مهلت قبل از تکمیل عملیات به پایان رسید. برای عملیاتی که وضعیت سیستم را تغییر می دهد، حتی اگر عملیات با موفقیت به پایان رسیده باشد، ممکن است این خطا برگردانده شود. به عنوان مثال، یک پاسخ موفقیت‌آمیز از یک سرور می‌توانست آنقدر به تأخیر بیفتد که مهلت آن به پایان برسد.

درخواست ناتوانی

عدم توانایی درخواست یک استراتژی مرکزی است که در APIهای پرداخت استاندارد استفاده می‌شود تا اطمینان حاصل شود که تعاملات سیستمی بین Google و شرکای قوی و قابل تحمل خطا است. درخواست‌های Idempotent درخواست‌هایی هستند که به طور بالقوه می‌توانند چندین بار ارسال شوند، اما اثری مشابه یک درخواست دارند. این استراتژی سازگاری نهایی بین سیستم‌ها را با ایمن کردن دوباره تلاش‌ها تسهیل می‌کند و به سیستم‌های ما اجازه می‌دهد تا در مورد وضعیت منبع به توافق برسند.

API ما از ناتوانی در موارد زیر استفاده می کند:

  • با ایجاد آسانی قابل ردیابی و ممیزی کردن همه اقدامات، مسائل مربوط به مصالحه را کاهش دهید.
  • با اطمینان از اینکه چندین درخواست یکسان از یک مشتری منجر به وضعیت نهایی متفاوت نمی شود، از شرایط مسابقه جلوگیری کنید.
  • به حداقل رساندن حالت با اجازه دادن به درخواست ها به صورت مجزا درک شوند و با حذف بار سرور ناشی از حفظ داده ها، عملکرد و توان عملیاتی بهبود یافته را ممکن می سازد.
  • از نیاز به فیلدهای اضافی برای نشان دادن اینکه آیا یک درخواست تکراری است اجتناب کنید

نمونه ها

مثال 1: اتصال قبل از دریافت پاسخ قطع شد

سناریو:

  1. گوگل درخواستی را به ادغام کننده ارسال می کند.
  2. سرور یکپارچه این درخواست را دریافت کرده و با موفقیت پردازش می کند.
  3. سرور Google قبل از دریافت پاسخ در مرحله 2، برق خود را از دست می دهد.
  4. قدرت سرور Google بازیابی می شود و همان درخواست با همه پارامترهای یکسان (همان شناسه درخواست و جزئیات درخواست اما requestTimestamp به روز شده) به سرور ادغام کننده ارسال می شود.

نتیجه:

در این مورد، سرور یکپارچه‌ساز باید با همان پاسخی که در مرحله #2 داده شده است، پاسخ دهد، زیرا تمام پارامترها، به جز responseTimestamp ، یکسان هستند. عارضه جانبی فقط یک بار، در مرحله 2 رخ می دهد. مرحله 4 هیچ عارضه جانبی ندارد.

مثال 2: درخواست ارسال شده به سروری که در حال تعمیر است

سناریو:

  1. پایگاه داده سرور یکپارچه برای تعمیر و نگهداری از کار افتاده است.
  2. گوگل درخواستی را به ادغام کننده ارسال می کند.
  3. یکپارچه ساز به درستی کد وضعیت UNAVAILABLE را برمی گرداند.
  4. سرور Google پاسخ را دریافت می کند و برای امتحان مجدد برنامه ریزی می کند.
  5. پایگاه داده سرور یکپارچه به صورت آنلاین باز می گردد.
  6. Google درخواست را از مرحله شماره 2 مجدداً ارسال می‌کند (همان شناسه درخواست و جزئیات درخواست، اما requestTimestamp به‌روزرسانی شده است). توجه داشته باشید که شناسه درخواست برای هر دو درخواست باید یکسان باشد.
  7. سرور یکپارچه درخواست را دریافت می کند و یک کد وضعیت OK را همراه با پاسخ کامل برمی گرداند.

نتیجه:

در این مورد، سرور یکپارچه‌ساز باید درخواست را در مرحله 7 پردازش کند و HTTP 503 ( UNAVAILABLE ) را برگرداند. در عوض، سرور یکپارچه باید به طور کامل درخواست را پردازش کند و با پیام مناسب، OK را برگرداند. توجه داشته باشید که در حالی که سیستم UNAVAILABLE Google ممکن است درخواست‌های مکرر مشابه مرحله 2 ارائه کند. هر درخواست باید به پیامی شبیه به مرحله 3 منجر شود. در نهایت، مرحله #6 و مرحله #7 رخ خواهد داد.

مثال 3: پیام تکرار شده به دلیل خطای بازیابی با پیام اولیه مطابقت ندارد

سناریو:

  1. گوگل درخواستی را به ادغام کننده ارسال می کند.
  2. سرور یکپارچه این درخواست را دریافت کرده و با موفقیت پردازش می کند.
  3. سرور Google قبل از دریافت پاسخ در مرحله 2، برق خود را از دست می دهد.
  4. قدرت سرور گوگل بازیابی شده و تلاش می کند همان درخواست را ارسال کند اما متاسفانه برخی از پارامترها متفاوت است.

نتیجه:

در این مورد، سرور یکپارچه‌ساز باید با کد خطای HTTP 412 ( PRECONDITION FAILED ) پاسخ دهد که به گوگل نشان می‌دهد که در این سیستم خطایی وجود دارد.