تطوير الدوال
قبل توزيع توزيع بوابة API، ستحتاج إلى تطوير الوظائف وتوزيعها.
حول منطق الأعمال
رمز الخصم الخاص بالتنفيذ هو وضع رمز ما في دالة. قد يكون هذا الرمز معقدًا حسب الحاجة، أو استدعاء نقاط انتهاء متعددة أو ربما يؤدي لإجراء بعض التجميع. وظيفة منطق الأعمال هي التعليمات البرمجية التي سيتم استدعاؤها عند الحاجة بواسطة بوابة Oracle Cloud Infrastructure API.
في هذا المثال من البنية، تقوم جيت واي API باستدعاء دالة Oracle، والتي بدورها تقوم بالاستعلام عن بعض البيانات من Oracle Fusion Applications Cloud Service من خلال REST API، ومعالجتها، وإرجاعها إلى المستخدم. عند كتابة الدالة نفسها، يمكنك استخدام أي إطار عمل مناسب ترغب في استخدامه، ولكن يجب أن تكون على دراية بتأثير إطار عمل معين فيما يتعلق بوظائف الخادم الأقل. في هذا المثال، قمنا باستخدام Java كلغة ومكتبة Apache HttpClient للاتصال بخدمة REST Service. تم اختيار مكتبة Apache لأنها كانت سهلة الاستخدام وتسهل في تنفيذها ؛ على الرغم من أنه في Java 11 كان لدينا الآن عميل HTTP جديد يمكن استخدامه أيضًا.
كما يجب تجنب تعامل الكثير من الكائنات المستخدمة في الذاكرة عند استدعاء واجهات Api لـ REST، ومن ثم سيتم تجاهل تلك الكائنات على كل استدعاء، ومن ثم يتم إبطال تنفيذ الدالة.
حول الحصول على أسماء المستخدمين والأدوار
عند استدعاء دالة بواسطة جيت واي Oracle Cloud Infrastructure API، تقوم جيت واي بإدخال بعض الميتاديتا في الاستدعاء باستخدام رؤوس HTTP. ويمكن الوصول إلى هذه الرؤوس باستخدام الوظائف SDK.
على سبيل المثال، في المقطع التالي من تعليمات Java البرمجية (تم استبعادها من الطبقة JWTUtils في مثال التعليمات البرمجية المقدمة مع دفتر تشغيل هذا الحل)، نقوم باستخراج مقطع التصديق وفك فك تشفيره ثم إعادته كجزء من النص إلى المتصل.
public OutputEvent handleRequest(InputEvent rawInput) {
Optional<string> optionalToken=rawInput.getHeaders().get("Fn-Http-H-Authorization");
if (!optionalToken.isPresent())
{
throw new Exception("No Authentication Bearer token found");
}
String jwtToken=optionalToken.get().substring(TOKEN_BEARER_PREFIX.length());
String[] split_string = jwtToken.split("\\.");
String base64EncodedHeader = split_string[0];
String base64EncodedBody = split_string[1];
String base64EncodedSignature = split_string[2];
byte[] decodedJWT = Base64.getDecoder().decode(base64EncodedBody);
try {
String JSONbody = new String(decodedJWT, "utf-8");
ObjectMapper mapper = new ObjectMapper();
JsonNode root=mapper.readTree(JSONbody);
username=root.get("sub").asText();
System.out.println(“Username = “+username);
} catch (Exception e)
{
Throw new Exception (e.getMessage());
}
Return OutputEvent.fromBytes(
username.getBytes(), // Data
OutputEvent.Status.Success,// Any numeric HTTP status code can be used here
"text/plain");يمكن استخدام اسم المستخدم داخل الوظيفة لتنفيذ منطق الأعمال كما هو مطلوب. الأدوار غير متاحة في الرمز المميز للتصديق، على أنه يمكن الاستعلام عنها من Oracle Identity Cloud Service باستخدام REST api.
عندما يستدعي Oracle API Gateway الدالة، يتم أيضًا إرسال عدد من الرؤوس المفيدة. ويمكن قراءة هذه الرؤوس باستخدام واجهة API للدالة. تتضمن الرؤوس المفيدة المتاحة من Functions Developer Kit ما يلي:
| Fn -الHttp - ethod | الأسلوب المستخدم لاستدعاء الدالة (GET/POST/PUT، إلخ). |
| Fn - Https - Url | عنوان URL المستخدم لاستدعاء الوظيفة، ويشمل ذلك معلمات الاستعلام. |
| Fn -العميل - الوكيل | تفاصيل العميل مثل نظام التشغيل والمورد والإصدار. |
على سبيل المثال، باستخدام توليفة من Fn - Https - method وFn - Http - Url يمكنك تنفيذ موجه في رمزك بحيث تقوم الوظيفة بعمل أشياء مرتبطة مختلفة بناءً على كيفية استدعائها (مثل PUT, PATCH, إلخ). هذا الأسلوب غالبًا ما يُسمى نمط “خدمة أقل "ويتميز المطور بالاحتفاظ بوظائف أقل ويكون لكل دالة موجه صغير يحدد ما يحتاجون عمله.
public OutputEvent handleRequest(InputEvent rawInput, HTTPGatewayContext hctx) throws JsonProcessingException {
String httpMethod = hctx.getMethod();
String httpRequestURI = hctx.getRequestURL();
// etc
} حول استدعاء Oracle Fusion Applications Cloud Service باستخدام مقطع الوصول لتأكيد JWT
يجب تنفيذ تأكيد JWT من Oracle Functions باستخدام الموضوع في رأس رسالة الاعتماد الواردة.
يمكن لوظيفة العينة المتوفرة مع دفتر تشغيل هذا الحل تنفيذ عملية التأمين هذه باستخدام مكتبة مساعد باسم idcsOAuthAsserter. تنفذ مكتبة المساعد تدفق تأكيد OAuth الكامل عن طريق إجراء تبادل مقاطع bearer قبل استدعاء Oracle Fusion Applications Cloud Service. هذه المكتبة متكاملة مع وظيفة العينة.
تتطلب الدالة توفر المفتاح الخاص والشهادة العامة لإنشاء تأكيدات المستخدم والعميل المستخدمة لاستدعاء Oracle Identity Cloud Service لتكوين مقطع وصول قاعدة بيانات bearer جديد باستخدام تأكيد OAuth JWT.
تتطلب المكتبة idcsOAuthAsserter بعض الخصائص التي يمكنك تعريفها في تكوين الدالة. جميع المتغيرات في الجدول التالي إلزامية:
| اسم التكوين | الوصف | مثال |
|---|---|---|
| IDCS_URL | عنوان URL لطبعة Oracle Identity Cloud Service | https ://<عنوان مضيف الخدمة السحابية للهوية.identity.oraclecloud.com> |
| CLIENT_ID | معرف عميل تطبيق Oracle Identity Cloud Service المقترن بـ Oracle Functions وOracle API Gateway | 1a2b3c4d5e6f7g8h9i01j2k3l4m5o6p7 |
| KEY_ID | الاسم البديل للشهادات التي تم استيرادها إلى تطبيق Oracle Identity Cloud Service الموثوق به | fnassertionkey |
| المجال | يجب أن يكون هذا المجال مطابقًا لمورد OAuth الهدف، وهو تطبيق Oracle Identity Cloud Service المقترن بـ Oracle Fusion Applications Cloud Service | urn:opc:resource:fa:instanceid=xxxxxxxurn:opc:resource:consumer: all https ://my_fusion_hostname:443/ |
| الجمهور | جمهور عملية التأكيد. مع فصل القيم المتعددة باستخدام الفواصل. | myhostname.identity.oraclecloud.com, https://myfusionservice.dc1.oraclecloud.com |
| IDDOMAIN | اسم عميل طبعة Oracle Fusion Applications Cloud Service | mytenant |
ستتطلب الدالة أيضًا خصائص التكوين للوصول إلى الثواني للتأكيد المرتبط بـ idcsOAuthAsserter. يتطلب تأكيد JWT شهادة ومفتاح خاص لإنشاء تأكيدات العميل والمستخدم. تسترجع الدالة مخزن المفاتيح باستخدام OCID المحدد في V_KEYSTORE. الاسم البديل لاسترجاع هذه المعلومات يجب أن تتطابق مع قيمة KEY_ID في التكوين. يجب استرجاع عبارة المرور لكل من مخزن المفاتيح ومفتاح الخصوصية من خدمة قطاعات Oracle Cloud Infrastructure Vault باستخدام OCIDs المحدد في V_KS_PASS وV_PK_PASS.
| اسم التكوين | الوصف | مثال |
|---|---|---|
| V_KEYSTORE | سري يحتوي على المحتوى الآمن المخزن لمخزن المفاتيح | ocid1.vaultsecret.oc1.dc1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| V_KS_PASS | كلمة السر السرية التي تحتوي على كلمة السر المخزنة الآمنة لمخزن المفاتيح | ocid1.vaultsecret.oc1.dc1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| V_PK_PASS | كلمة السر التي تحتوي على كلمة السر المخزنة المؤمنة للمفتاح الخاص | ocid1.vaultsecret.oc1.dc1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
قيمة تكوين إضافية مدعومة هي الخاصية USE_CACHE_TOKEN، وهي معينة إلى True بشكل افتراضي. تسمح لك هذه الخاصية بتخزين مقطع تأكيد Oracle Identity Cloud Service الذي تم إنشاؤه ليتم إعادة استخدامه في مخازن Oracle Fusion Applications Cloud Service المستقبلية، طالما ظلت المقاطع صالحة. يتم تدقيق المقطع المخزن في الذاكرة المخبئية قبل استخدامه بمقارنة الموضوع بالمقطع الوارد والتحقق من وقت انتهاء الصلاحية للتحقق مما إذا كان صالحًا أم لا. في حالة عدم حدوث ذلك، يتم طلب مقطع وصول جديد باستخدام تأكيد OAuth. يمكن تعطيل هذه السمة عن طريق تعيين USE_CACHE_TOKEN إلى False.
يمكن أن تستخدم الدالة المطلوب تنفيذها SecurityHelper object من مكتبة idcsOAuthAsserter لاستخراج الموضوع من رأس access-token، وإنشاء مقطع وصول إلى حامل جديد يشتمل على تأكيد OAuth JWT، وإرسال طلب إلى Oracle Fusion Applications Cloud Service باستخدام مقطع الوصول الجديد كرأس Authorization.
الدالة saasopportunitiesfn في عينة التعليمات البرمجية المصدر متكاملة بالفعل مع مكتبة idcsOAuthAsserter. جزء التعليمات البرمجية التالي متاح في handleRequest metdhod الخاص بوظيفة العينة، والذي يعرض كيفية تهيئة كائنات idcsOAuthAsserter وتنفيذ إلحاق المقاطع باستخدام التوكيد مع Oracle Identity Cloud Service:
// Full Oauth scenario Perform exchange of tokens
if(fullOAauth) {
LOGGER.log(Level.INFO, "Full Oauth Assertion scenario - Perform exchange of tokens");
SecurityHelper idcsSecurityHelper = new SecurityHelper(context) // Initialize SecurityHelper with RuntimeContext
.setOciRegion(Region.US_PHOENIX_1) // Specify the OCI region, used to retrieve Secrets.
.extractSubFromJwtTokenHeader(rawInput); // Extracts the subject from Token in Fn-Http-H-Authorization.
// Get OAuth Access token with JWT Assertion using the principal extracted from Fn-Http-H-Access-Token Header
jwttoken = idcsSecurityHelper.getAssertedAccessToken();
LOGGER.log(Level.INFO, "Successfully token retrived with IDCS Assertion");
LOGGER.log(Level.FINEST, "Access Token from assertion [" + jwttoken + "]");
}إشعار في هذا المقطع أنه تمت تهيئة الكائن SecurityHelper مع كائن سياق من النوع RuntimeContext. سيستخدم هذا في تهيئة SecurityHelper بتكوين مكتبة idcsOAuthAsserter Helper.
تم تعيين مثال دالة saasopportunitiesfn لاستخدام المنطقة US_PHOENIX_1، لذا يجب عليك تغيير المنطقة في الأسلوب setOciRegion المعروض في المقطع للإشارة إلى المنطقة الخاصة بك.
SecurityHelper تشتمل أيضًا على الأسلوب extractSubFromJwtTokenHeader الذي يأخذ كائن InputEvent من أسلوب الدالة handleRequest لاستخراج مقطع الحامل الذي يأتي في رأس بوابة API Authorization. ثم يجب أن تكون قادرًا على استرجاع مقطع الوصول كنتيجة لتأكيد Oracle Identity Cloud Service.
لمزيد من المعلومات حول استخدام idcsOAuthAsserter وتكامله مع دالة، راجع الملف README الخاص بـ idcsOAuthAsserter في مخزن الرموز باستخدام عينة التعليمات البرمجية القابلة للتنزيل المصاحبة لسجل تشغيل هذا الحل.
تعيين معلمات التكوين
توفر بيئة Oracle Functions جزءًا مفيدًا جدًا من الوظائف حيث يمكنك تعريف بعض المعلمات في بيئة Oracle Cloud Infrastructure ثم الإشارة إليها من التعليمات البرمجية.
في حالة الاستخدام هذه يتم تعيين عناوين URL لمقطع Fusion وOverrideJWT وعلامة تسمى full_oauth، كمعلمات يتم استخدامها في التعليمات البرمجية. لإضافة معلمات:
ضمن التعليمات البرمجية، يمكنك الوصول إلى متغيرات التكوين هذه باستخدام ملف SDK الخاص باستخدام تعليق Java التوضيحي (@FnConfiguration) الخاص والوصول إلى المعلمات من خلال متغير السياق:
private String jwtoverride = "";
private String fusionHostname = "";
private String fnURIBase ="/fnsaaspoc/opportunities";
/**
* @param ctx : Runtime context passed in by Fn
*/
@FnConfiguration
public void config(RuntimeContext ctx) {
fusionHostname = ctx.getConfigurationByKey("fusionhost").orElse("NOTSET");
jwtoverride = ctx.getConfigurationByKey("overridejwt").orElse("NOTSET");
fullOAauth = Boolean.parseBoolean(ctx.getConfigurationByKey("full_oauth").orElse("false"));
LOGGER.info("Configuration read : jwt=" + jwtoverride + " saasurl=" + fusionHostname);
}بالإضافة إلى ذلك، حيث يستخدم هذا الحل مكتبة مساعد idcsOAuthAsserter، ستحتاج إلى توفير المتغيرات المحددة الموضحة في القسم السابق لاستخدام تأكيد Oracle Identity Cloud Service OAuth في تبادل مقاطع الوصول. نظرًا لأن هذه العملية تتطلب العديد من عمليات التكوين الإلزامية، نقترح عليك تعيين تكوين الوظيفة باستخدام طريقة ملف yaml. على سبيل المثال:
config:
AUDIENCE: <AUDIENCE_VALUES>
CLIENT_ID: <YOUR_CLIENT_ID>
IDCS_URL: <YOUR_IDCS_URL>
IDDOMAIN: <YOUR_FA_TENANT_NAME>
KEY_ID: <YOUR_IDCS_URL>
SCOPE: <FA_RESOURCE_SCOPE>
V_KEYSTORE: <YOUR_KS_OCID>
V_KS_PASS: <YOUR_KSPASS_OCID>
V_PK_PASS: <YOUR_PKPASS_OCID>
fusionhost: <value>
overridejwt: <value>
full_oauth: <value>تمرير مقطع تصديق المستخدم إلى Fusion Applications
تحتاج الوظيفة إلى معالجة مقطع تصديق المستخدم لاتصالات REST API الآمنة.
عندما يتم استدعاء الدالة، يتم أيضًا إرسال متغير رأس “اعتماد” والذي قد يحتوي على مقطع تصديق. يتم إنشاء هذا المقطع بواسطة خادم هوية تطبيق الاستدعاء وهو نفس خادم الهوية الذي تستخدمه دالة جيت واي Oracle Cloud Infrastructure API لتدقيق الطلب.
يمثك الأسلوب الموضح في دفتر تشغيل هذا الحل في استخدام تأكيد Oracle Identity Cloud Service OAuth JWT لإجراء تبادل المقاطع باستخدام مكتبة مساعد idcsOAuthAsserter. يوفر هذا طبقة تأمين إضافية للاستدعاء من Oracle Functions إلى Oracle Fusion Applications Cloud Service. كما هو موضح في الرسم التخطيطي للبنية، تقوم الوظيفة باستعلامات تأكيد OAuth JWT للمقطع الذي يأتي في استدعاء الوارد من عنوان بوابة واجهة برمجة التطبيقات ويستخدمها لمقطع آخر أثناء عملية التأكيد مع Oracle Identity Cloud Service. سيتم استخدام هذا المقطع الجديد في الاستدعاء الخارجي لخادم الوجهة (Oracle Fusion Applications Cloud Service) وسيقوم (Oracle Fusion Applications Cloud Service) بتنفيذ الاستدعاء كمستخدم في Oracle Visual Builder.
في دالة العينة المتوفرة (saasopportunitiesfn)، يوجد تكوين بالاسم full_oauth، والذي يتم تعيينه بشكل افتراضي على True، وسيكون السلوك الموضح أعلاه.
بشكل اختياري، يمكنك تعيين full_oauth إلى False. وفي هذه الحالة، تقوم الوظيفة بالاستعلام عن المقطع الذي يأتي في المكالمة الواردة من عنوان بوابة واجهة برمجة التطبيقات (API) ثم إعادة استخدامه في المكالمة الخارجية في Oracle Fusion Applications Cloud Service. لم يتم إنشاء مقطع ثان.
يستخدم مقطع التعليمات البرمجية التالي مكتبة Apache HTTP واستدعاء Oracle Fusion Applications Cloud Service REST API باستخدام مقطع التصديق الذي تم تمريره.
String fusionURL=”<yourfusionresturl>”;
HttpClient client = HttpClients.custom().build();
HttpUriRequest request = RequestBuilder.get().setUri(fusionURL).
setHeader(HttpHeaders.CONTENT_TYPE, "application/json").
setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + jwtToken).
build();
HttpResponse response = client.execute(request);
responseJson = EntityUtils.toString(response.getEntity());
status = response.getStatusLine().getStatusCode();تعريف وظيفة التصديق بشكل اختياري في Oracle Cloud Infrastructure
تقوم جيت واي Oracle Cloud Infrastructure API بدعم IDCS يدويًا كموفر تصديق. على أن جيت واي تسمح أيضًا بتعريف دالة يمكن استدعاؤها. بشكل اختياري، يمكنك تكوين وظيفة تصديق مخصصة باستخدام هذه السمة.
تتلقى دالة التصديق المخصصة مكالمة من جيت واي، تمرر رأس الصلاحيات الواردة. إذا أرجعت الدالة القيمة حقيقي true، يتم السماح باستدعاء الدالة؛ على العكس إذا أعاد القيمة غير حقيقي false، فسيتم رفض الطلب برمز خطأ HTTP 401. يتم توفير الدالة في صيغة التعليمات البرمجية المصدر ويتم توزيعها ضمن الدوال، والتي تتم الإشارة إليها بعد ذلك في ملف توزيع OCI API gatecy عبر OCID الخاص بها. يمكنك اكتشاف Ocd عبر الانتقال إلى الدالة الموزعة في وحدة التحكم وتوسيع عمود OCID الخاص بها. قبل التمكن من توزيع الدالة ، يلزم تحرير الملف ResourceServerConfig.java ؛ وهو يحدد كيفية اتصال الدالة بـ Oracle Identity Cloud Service ومن ثم استخدام تطبيق Oracle Identity Cloud Service OAuth.
إن مثال الدالة أدناه يمنع مشاركة قيم البيانات الحساسة مثل كلمة سر العميل. في السطور الأربعة أسفل التعليق // KMS Key for IDCS Client Secret، تقوم التعليمات البرمجية بفك تشفير بيانات OAuth secret باستخدام سمة إدارة مفاتيح Oracle Cloud Infrastructure، وOracle Cloud Infrastructure Vault. يمكن إدخال هذه القيم في وحدة تحكم Oracle Cloud Infrastructure الطرفية قبل توزيع الدالة.