اشکال‌زدایی افزونه

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

می‌توانید بااستفاده از پیام‌های نمایان در دو مکان، افزونه‌ای را اشکال‌زدایی کنید: ابزار «ردیابی» و گزارش‌های افزونه. وقتی افزونه‌ای کار نمی‌کند، شناسایی مشکل گاهی اوقات به اطلاعات هر دو مکان نیاز دارد.

• ابزار ردیابی Apigee Edge جایی است که در آن کد پراکسی API را به‌صورت تکراری آزمایش و ویرایش می‌کنید. پیام‌های ردیابی شامل خطاهای کد پراکسی API شما، ازجمله پیکربندی خط‌مشی و پراکسی API است.

  خطاهای مربوط به افزونه که در ابزار «پیگیری» ظاهر می‌شوند معمولاً جزئیات زیادی ندارند، به‌جز اینکه بگویند کدام پیام‌واره افزونه ناموفق بوده است، همراه با کد خطای HTTP. وقتی چیزی مفید در اینجا نمی‌بینید، بهترین مکان بعدی برای جستجو، گزارش افزونه‌ای است که استفاده می‌کنید.

• افزونه‌ها در زمان اجرا ورودی‌های گزارش تولید می‌کنند. (گزارش‌های افزونه فقط برای سرپرستان سازمان دردسترس است.)

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

  گزارش‌ها همچنین شامل ورودی‌هایی از کد افزونه داخلی است. هنگام بررسی گزارش‌ها، به‌خاطر داشته باشید که برخی‌از ورودی‌ها به خطایی که درحال اصلاح آن هستید مربوط نیستند. ورودی‌های گزارش مربوط به افزونه معمولاً با کلمه details شروع می‌شوند، مانند ورودی گزارش زیر از افزونه Cloud Pub/Sub:

  details: 'Invalid resource name given (name=projects/example-test-123456/topic/extension-example). Refer to https://cloud.google.com/pubsub/docs/admin#resource_names for more information.'
  

انواع و دلایل خطا

جریان پردازش درخواست افزونه از خط‌مشی «دعوت به اقدام افزونه» در یک پراکسی API، ازطریق افزونه، به منبع خارجی، و سپس دوباره به داخل برمی‌گردد. بنابراین خطا می‌تواند در هریک از این مکان‌ها رخ دهد.

خطاهایی که می‌بینید ممکن است در دسته‌های زیر قرار بگیرند.

خطا در پیکربندی افزونه

این پیکربندی‌ای است که سرپرست سازمان هنگام افزودن افزونه به محیط انجام می‌دهد.

برای مثال، اگر افزونه «گزارش‌گیری ابری» را با شناسه پروژه Google Cloud نادرستی پیکربندی کنید، «گزارش‌گیری ابری» Google خطایی به افزونه برمی‌گرداند. جزئیات مربوط به این خطاها معمولاً در گزارش افزونه است.

شواهد در ابزار «ردیابی»

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

{
  "fault": {
    "faultstring":"Execution of ConnectorCallout Logging-Extension failed. Reason: Connector returned error statuscode=500",
    "detail": {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

شواهد در گزارش‌های افزونه

اگر جزئیاتی درباره این نوع خطا وجود داشته باشد، آن را در ورودی‌های گزارش افزونه خواهید دید. پیام خطای زیر که توسط سرویس Cloud Pub/Sub برگردانده شده است، ناشی از شناسه پروژه بدشکل است.

details: 'Project does not exist: example-test-12345'

خطاها در پیکربندی خط‌مشی «افزونه‌نوشته‌راهنما»

این خطاها زمانی رخ می‌دهند که خط‌مشی «افزونه‌نوشته‌راهنما» به‌درستی پیکربندی نشده باشد، یا ازطریق خطای دستورگان پیکربندی خط‌مشی یا ازطریق کلیدها یا مقادیر پیکربندی نادرست. این خطاها بسته به نحوه پیکربندی خط‌مشی، دو شکل دارند:

• مقادیر نادرست ارزیابی‌شده توسط منبع خارجی

  این خطا زمانی رخ می‌دهد که خطای پیکربندی برای افزونه معتبر به‌نظر می‌رسد، اما برای منبع خارجی نامعتبر است. برای مثال، اگر افزونه شناسه پایگاه داده نادرستی را به Cloud Spanner ارسال کند، Cloud Spanner خطایی را برمی‌گرداند که در گزارش افزونه ثبت می‌شود:

  details: 'Database not found: projects/example-test-123456/instances/spanner-extension-example-db/databases/my-business-d'
  

  این خطا همچنین می‌تواند به‌دلیل پیکربندی نادرست JSON در عنصر <Input> خط‌مشی رخ دهد. برای برخی‌از افزونه‌ها، بخشی از JSON توسط افزونه پردازش می‌شود و بخشی به منبع منتقل می‌شود. برای مثال، پیکربندی JSON افزونه Cloud Logging شامل شیء metadata است که محتوای آن به Cloud Logging منتقل می‌شود. نام‌های کلید نادرست در آنجا—مثلاً typ به‌جای type—می‌تواند خطاهایی از منبع خارجی برگرداند که به‌صورت ورودی در گزارش افزونه ظاهر می‌شوند:

  details: 'Resource type cannot be empty'
  

• مقادیر نادرست ارزیابی‌شده توسط افزونه

  این خطاها شامل خطاهای نحوی در بخش‌های ارزیابی‌شده خط‌مشی عنصر <Input> در JSON، غلط نوشتن نام کنش در عنصر <Action>، و غیره می‌شود. این خطاها معمولاً در ابزار «ردیابی» ظاهر می‌شوند، اما در گزارش‌های افزونه ظاهر نمی‌شوند.

شواهد در ابزار «ردیابی»

در ویرایشگر پراکسی، این خطاها معمولاً به‌صورت خطای سطح 4xx یا 5xx نشان داده می‌شوند. بااین‌حال، ویرایشگر پراکسی هیچ جزئیاتی درباره علت خطا نمایش نمی‌دهد، فقط می‌گوید که افزونه خطا برگردانده است. وقتی نام کنش در افزونه Cloud Firestore اشتباه نوشته می‌شود، خطای زیر در ابزار «ردیابی» نشان داده می‌شود.

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404","detail":
    {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

شواهد در گزارش‌های افزونه

وقتی پیکربندی خط‌مشی منجر به خطای پردازش در منبع خارجی شود، معمولاً خطا در گزارش ظاهر می‌شود.

خطاهای مربوط به درخواست افزونه برای منبع

این خطا زمانی رخ می‌دهد که درخواست منبع خارجی به دلایلی که مربوط به افزونه نیست موفقیت‌آمیز نباشد.

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

شواهد در ابزار «ردیابی»

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

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404",
    "detail":{
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

شواهد در گزارش‌های افزونه

گزارش معمولاً دارای ورودی‌هایی با پیام‌هایی از خود منبع خارجی است. پیام گزارش زیر از Cloud Spanner خطای مقدار کلید اصلی موجود را شرح می‌دهد.

details: 'Row [jonesy42] in table user already exists'