التعامل مع الأمان والأخطاء والتحذيرات والتسجيل
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يغطي هذا القسم الموضوعات التالية:
الأمان
يمكن أن يعمل مصدر البيانات في أحد وضعَي الوصول على النحو التالي:
-
في
وضع الوصول المقيّد، وهو الإعداد التلقائي، لا يعرض مصدر البيانات إلا تلك الطلبات التي تنشأ من النطاق نفسه الذي يتوفّر فيه مصدر البيانات. يمنع "وضع تقييد المحتوى" هجمات تزوير الطلبات من مواقع إلكترونية متعددة (XSRF)، ولذلك أكثر أمانًا من وضع الوصول غير المحدود. نظرًا لأن مكتبة مصادر البيانات توفر واجهة لعرض البيانات فقط، وليس لتغيير الحالة أو البيانات من جهة الخادم، تكون هجمات XSRF التي تحاول سرقة البيانات متاحة فقط. لجعل مصدر بياناتك آمنًا من محاولات سرقة البيانات، يجب استخدام وضع تقييد المحتوى جنبًا إلى جنب مع المصادقة المستندة إلى ملفات تعريف الارتباط.
تعتمد طريقة مصادقة المستخدمين على بيئتك وتنفيذها.
-
في وضع الوصول غير المحدود، يعرض مصدر البيانات جميع الطلبات
بغض النظر عن مصدرها. ويمكن حماية مصدر البيانات الذي يتم تشغيله في "وضع تقييد المحتوى" من خلال المصادقة المستندة إلى ملفات تعريف الارتباط، ولكن يُرجى العلم أنّ مصدر البيانات سيكون عرضةً لهجمات XSRF. استخدِم "وضع تقييد المحتوى" إذا كانت المرئيات على صفحات الويب خارج نطاق مصدر البيانات تحتاج إلى الوصول إلى مصدر البيانات، أو إذا كانت البيانات في النطاق العام وبالتالي لا تحتاج إلى حمايتها.
يمكن لطلب التصور تحديد تنسيق استجابة
هو JSON أو CSV أو HTML. يحدد تنسيق الاستجابة التنسيق الذي
يرجع به مصدر البيانات جدول بيانات. نظرًا لأن تنسيقات CSV وHTML ليست عرضة لهجمات XSRF، فيمكن الوصول إليها من نطاقات أخرى، حتى في وضع تقييد المحتوى.
لتحديد وضع عدم تقييد المحتوى، يمكنك إلغاء isRestrictedAccessMode() على النحو التالي:
@Override
protected boolean isRestrictedAccessMode() {
return false;
}
للتبسيط، يتم تشغيل جميع الأمثلة المتوفرة مع المكتبة في وضع الوصول غير المقيّد.
الأخطاء والتحذيرات
عندما يتعذّر عرض جدول بيانات صالح أو لا يُنصح به،DataSourceException. على سبيل المثال، إذا لم تتمكن
من مصادقة المستخدم. تطرح المكتبة هذه الاستثناءات عندما تمنعها
الأخطاء من إنشاء جدول بيانات. قد ترغب في طرح استثناءات في
مواقف فريدة لمصدر بياناتك. إذا كان الأمر كذلك، عليك إنشاء أنواع استثناءات الأخطاء من خلال اكتسابها من الفئة DataSourceException. ويمكنك أيضًا طرح الفئة DataSourceException مباشرةً.
توجد الفئة DataSourceException
في الحزمة base، وتأخذ المعلمات التالية:
ReasonType
هذه المَعلمة إلزامية. يتم تحديد أنواع الأسباب
المتاحة في تعداد ReasonType. إذا لم يكن أيّ من أنواع الأسباب المتوفّرة مناسبًا، يمكنك استخدام Other أو Internal.
MessageToUser
تحدّد هذه المَعلمة نص رسالة الخطأ.
في معظم الحالات، يتم عرض هذا النموذج للمستخدم كتلميح، لذا من المهم عدم تضمين معلومات فنية أو سرية.
يمكنك استخدام مجموعة الدوال المساعدة
في datasource.DataSourceHelper لمعالجة الأخطاء. في هذه الحالة، يمكنك استدعاء دالتين بالاسم نفسه setErrorServletResponse لأخذ DataSourceException وتعيين خطأ في استجابة serlet للبيانات. تستخدم إحدى هذه الدوال طلب مصدر بيانات، والدالة الأخرى تأخذ HttpServlet request ويتم استخدامها في الحالات التي يتعذر فيها إنشاء DataSourceRequest. في ما يلي مثال على عملية التنفيذ في تحديد الإمكانيات وتدفق الأحداث.
إذا كان لا يمكن إرجاع جدول بيانات، فستعرض المكتبة خطأ. إذا كان من الممكن إرجاع جدول بيانات، ولكن توجد مشكلة للإبلاغ، تعرض المكتبة تحذيرًا مع جدول البيانات.
على سبيل المثال، تنشئ المكتبة تحذيرًا في الحالات التالية:
- إذا كان العرض المرئي لطلب البحث يوفّر
LIMIT، ما يؤدي إلى اقتطاع البيانات.
- إذا كان التمثيل البصري لطلب البحث يطلب نمط تنسيق غير صالح
في إحدى فقرات
FORMAT.
لإضافة تحذيرك الخاص، يمكنك إنشاء مثيل من base.Warning وإضافته إلى جدول البيانات باستخدام الطريقة addWarning().
التسجيل
تستخدم المكتبة قطع الأشجار في جاكرتا كومنز. يمكن استخدام تسجيل الدخول في جاكرتا
مع معظم أنظمة التسجيل الشائعة التي قد تكون لديك بالفعل. قد تحتاج إلى كتابة محوّل إذا كان نظام التسجيل لديك غير عادي.
لمزيد من التفاصيل، يُرجى الاطّلاع على الصفحة الرئيسية لتسجيل
Jakartacommons.
عندما يتم طرح استثناء، يتم إرسال المعلومات إلى السجل. تعتمد طريقة الوصول إلى السجل على نظام التسجيل الذي تستخدمه.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-07-10 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2024-07-10 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThis documentation provides information about security considerations, error handling, and logging within the data source library.\u003c/p\u003e\n"],["\u003cp\u003eData sources operate in restricted access mode by default to prevent XSRF attacks, but unrestricted mode can be enabled for cross-domain access.\u003c/p\u003e\n"],["\u003cp\u003eThe library uses \u003ccode\u003eDataSourceException\u003c/code\u003e for errors, with helper functions available to handle these errors in servlet responses.\u003c/p\u003e\n"],["\u003cp\u003eWarnings are used to indicate problems without preventing data table return, like truncated data due to limits or invalid formatting.\u003c/p\u003e\n"],["\u003cp\u003eLogging is handled through Jakarta commons logging, which can be adapted to various logging systems.\u003c/p\u003e\n"]]],[],null,["# Handling Security, Errors, Warnings, and Logging\n\nThis section covers the following topics:\n\n- [Security](#access)\n- [Errors and Warnings](#error)\n- [Logging](#logging)\n\nSecurity\n--------\n\nA data source can operate in one of two access modes as follows:\n\n- In\n restricted access mode, which is the default, a data source serves only\n those requests that originate from the same domain as that in which the\n data source is located. Restricted mode prevents [cross-site\n request forgery](http://en.wikipedia.org/wiki/Cross-site_request_forgery) (XSRF) attacks and so is more secure than unrestricted\n access mode. Because the data source library provides an interface for\n returning data only, and not for changing state or data on the server side,\n only XSRF attacks\n that attempt to steal data are possible. To\n make your data source secure against attempts to steal data, restricted\n mode must be used in conjunction with cookie-based authentication.\n The way that you authenticate users depends on your environment and implementation.\n\n- In unrestricted access mode, a data source serves all requests\n regardless of their origin. A data source that runs in unrestricted mode\n can be protected by cookie-based authentication, but note that\n the data source will be vulnerable to\n XSRF attacks. Use unrestricted mode if visualizations on web pages outside the data source's\n domain need to access the data source, or if the data is in the public\n domain and so does not need to be protected.\n\nA visualization request can specify a response\nformat of JSON, CSV, or HTML. The response format determines the format\nin which a data source returns a data table. Because CSV and HTML formats\nare not vulnerable to XSRF attacks, these can be accessed from other domains,\neven in restricted mode.\n\nTo specify unrestricted mode, override `isRestrictedAccessMode()` as\nfollows: \n\n```transact-sql\n @Override\n protected boolean isRestrictedAccessMode() {\n return false;\n }\n```\n\nFor simplicity, all the examples provided with the library run in unrestricted\naccess mode.\n\nErrors and Warnings\n-------------------\n\nWhen it is not possible, or desirable, to return a valid data table, the\nlibrary throws a `DataSourceException`. For example if\nthe user cannot be authenticated. The library throws these exceptions\nwhen errors prevent it from creating a data table. You may want to throw\nexceptions in situations unique to your data source. If so,\ncreate your own error exception types by inheriting from the `DataSourceException`\nclass. You can also throw the `DataSourceException` class\ndirectly.\n\nThe `DataSourceException` class\nis located in the `base` package, it takes the following parameters: \n\n- `ReasonType` \n This parameter is mandatory. Available reason types are defined in the `ReasonType` enum. If none of the available reason types are suitable, you can use `Other` or `Internal`. \n- `MessageToUser` \n This parameter defines the text of the error message. In most cases, it is displayed to the user as a tooltip, so it is important not to include technical or confidential information.\n\nYou can use the set of helper functions\nin `datasource.DataSourceHelper` to handle\nerrors. In this case call two functions both with same name of `setErrorServletResponse` to\ntake a `DataSourceException` and set an error on the data\nservlet response. One of these functions takes a data source request, the\nother takes an `HttpServlet request` and is used in cases\nwhere there is a failure to create a `DataSourceRequest`. An\nexample implementation is provided in [Defining Capabilities and the Flow of Events](/chart/interactive/docs/dev/dsl_httpservlet).\n\nIf it is not possible to return a data table, the library returns an\nerror. If it is possible to return a data table, but there is a problem\nto report, the library returns a warning together with the data table.\nFor example, the library\ncreates a warning in the following situations:\n\n- if a querying visualization provides a `LIMIT` that results in truncated data.\n- if a querying visualization requests an invalid formatting pattern in a `FORMAT` clause.\n\nTo add your own warning,\ncreate an instance of `base.Warning` and add it to your\ndata table using the `addWarning()` method.\n\nLogging\n-------\n\nThe library uses Jakarta commons logging. Jakarta commons logging can\nbe used with most common logging systems that you might already have in\nplace. You might need to write an adapter if your logging system is non-standard.\nFor more details, see the [Jakarta\ncommons logging home page](http://commons.apache.org/logging/).\n\nWhen an exception is thrown information is sent to the log. The way\nthat you access the log depends on the logging system you use."]]
