أداة لتشغيل تطبيقات الويب على AWS Lambda
يتيح AWS Lambda Web Adaptor للمطورين إنشاء تطبيقات ويب (http api) باستخدام أطر عمل مألوفة (مثل Express.js وNext.js وFlask وSpringBoot وASP.NET وLaravel، وأي شيء يتحدث HTTP 1.1/1.0) وتشغيله على AWS Lambda . يمكن تشغيل نفس صورة عامل الإرساء على AWS Lambda، وAmazon EC2، وAWS Fargate، وأجهزة الكمبيوتر المحلية.
يعمل AWS Lambda Web Adaptor مع وظائف Lambda المجمعة كصور عامل إرساء وحزم Zip.
لاستخدام Lambda Web Adaptor مع صور عامل الإرساء، قم بتعبئة تطبيق الويب الخاص بك (http api) في ملف Dockerfile، وأضف سطرًا واحدًا لنسخ الملف الثنائي Lambda Web Adaptor إلى /opt/extensions داخل الحاوية الخاصة بك:
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.4 /lambda-adapter /opt/extensions/lambda-adapter
يمكن استخدام الصور الأساسية غير التابعة لـ AWS نظرًا لأن Runtime Interface Client يأتي مع Lambda Web Adaptor.
افتراضيًا، يفترض Lambda Web Adaptor أن تطبيق الويب يستمع على المنفذ 8080. وإذا لم يكن الأمر كذلك، فيمكنك تحديد المنفذ عبر التكوين.
يتم توفير ثنائيات Lambda Web Adaptor المجمعة مسبقًا في مستودع ECR العام: public.ecr.aws/awsguru/aws-lambda-adapter. يتم أيضًا توفير صور متعددة الأقواس في هذا الريبو. إنه يعمل على بنية وحدة المعالجة المركزية x86_64 وarm64.
يوجد أدناه ملف Dockerfile للحصول على مثال لتطبيق Nodejs.
FROM public.ecr.aws/docker/library/node:20-slim
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.4 /lambda-adapter /opt/extensions/lambda-adapter
ENV PORT=7000
WORKDIR "/var/task"
ADD src/package.json /var/task/package.json
ADD src/package-lock.json /var/task/package-lock.json
RUN npm install --omit=dev
ADD src/ /var/task
CMD [ "node" , "index.js" ]
يعمل هذا مع أي صور أساسية باستثناء الصور الأساسية المُدارة بواسطة AWS. لاستخدام الصور الأساسية المُدارة بواسطة AWS، يتعين عليك تجاوز ENTRYPOINT لبدء تطبيق الويب الخاص بك.
يعمل AWS Lambda Web Adaptor أيضًا مع أوقات تشغيل Lambda التي تديرها AWS. عليك أن تفعل ثلاثة أشياء:
قم بإرفاق طبقة Lambda Web Adaptor بوظيفتك.
arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:23
arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:23
arn:aws-cn:lambda:cn-north-1:041581134020:layer:LambdaAdapterLayerX86:23
arn:aws-cn:lambda:cn-northwest-1:069767869989:layer:LambdaAdapterLayerX86:23
قم بتكوين متغير بيئة Lambda AWS_LAMBDA_EXEC_WRAPPER
على /opt/bootstrap
.
قم بتعيين معالج الوظيفة على البرنامج النصي لبدء تشغيل تطبيق الويب الخاص بك. على سبيل المثال run.sh
.
للحصول على التفاصيل، يرجى مراجعة مثال تطبيق Node.js.
عند بدء تشغيل بيئة تنفيذ Lambda جديدة، سيتم تشغيل Lambda Web Adaptor كملحق Lambda، متبوعًا بتطبيق الويب.
افتراضيًا، سيرسل Lambda Web Adaptor طلبات HTTP GET إلى تطبيق الويب على http://127.0.0.1:8080/
. يمكن تخصيص المنفذ والمسار باستخدام متغيري البيئة: AWS_LWA_READINESS_CHECK_PORT
و AWS_LWA_READINESS_CHECK_PATH
.
سيعيد Lambda Web Adaptor محاولة هذا الطلب كل 10 مللي ثانية حتى يُرجع تطبيق الويب استجابة HTTP ( رمز الحالة >= 100 و<500 ) أو تنتهي مهلة الوظيفة.
بالإضافة إلى ذلك، يمكنك تكوين المحول لإجراء فحص الاستعداد باستخدام اتصال TCP، عن طريق تعيين AWS_LWA_READINESS_CHECK_PROTOCOL
على tcp
.
بعد اجتياز فحص الجاهزية، سيبدأ Lambda Web Adaptor تشغيل Lambda Runtime وإعادة توجيه الاستدعاءات إلى تطبيق الويب.
يمكن تكوين منفذ/مسار فحص الجاهزية ومنفذ حركة المرور باستخدام متغيرات البيئة. يمكن تعريف متغيرات البيئة هذه إما داخل ملف عامل الإرساء أو كتكوين دالة Lambda.
متغير البيئة | وصف | تقصير |
---|---|---|
AWS_LWA_PORT / ميناء* | ميناء المرور | "8080" |
AWS_LWA_READINESS_CHECK_PORT / READINESS_CHECK_PORT* | منفذ التحقق من الجاهزية، الافتراضي هو منفذ حركة المرور | ميناء |
AWS_LWA_READINESS_CHECK_PATH / READINESS_CHECK_PATH* | مسار التحقق من الاستعداد | "/" |
AWS_LWA_READINESS_CHECK_PROTOCOL / READINESS_CHECK_PROTOCOL* | بروتوكول التحقق من الجاهزية: "http" أو "tcp"، الافتراضي هو "http" | "http" |
AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS | الحد الأدنى لرمز حالة HTTP الذي يعتبر غير صحي | "500" |
AWS_LWA_ASYNC_INIT / ASYNC_INIT* | تمكين التهيئة غير المتزامنة لوظائف التهيئة الطويلة | "خطأ شنيع" |
AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH* | المسار الأساسي المراد إزالته من مسار الطلب | لا أحد |
AWS_LWA_ENABLE_COMPRESSION | تمكين ضغط gzip لنص الاستجابة | "خطأ شنيع" |
AWS_LWA_INVOKE_MODE | وضع استدعاء دالة Lambda: "مخزن مؤقت" أو "response_stream"، الافتراضي هو "مخزن مؤقت" | "مخزنة" |
AWS_LWA_PASS_THROUGH_PATH | مسار تلقي حمولات الأحداث التي يتم تمريرها من خلال مشغلات غير http | "/الأحداث" |
AWS_LWA_AUTHORIZATION_SOURCE | اسم رأس ليتم استبداله Authorization | لا أحد |
ملاحظة: نستخدم البادئة "AWS_LWA_" لتعيين مساحة الاسم لجميع متغيرات البيئة التي يستخدمها Lambda Web Adaptor. سيتم دعم الإصدارات الأصلية حتى نصل إلى الإصدار 1.0.
AWS_LWA_PORT / PORT - سيرسل Lambda Web Adaptor حركة المرور إلى هذا المنفذ. هذا هو المنفذ الذي يستمع إليه تطبيق الويب الخاص بك. داخل بيئة تنفيذ Lambda، يعمل تطبيق الويب كمستخدم غير جذر، ولا يُسمح له بالاستماع على المنافذ الأقل من 1024. يُرجى أيضًا تجنب المنفذ 9001 و3000. Lambda Runtime API موجود على المنفذ 9001. يستخدم ملحق CloudWatch Lambda Insight المنفذ 3000 .
AWS_LWA_ASYNC_INIT / ASYNC_INIT - توفر أوقات التشغيل المُدارة من Lambda ما يصل إلى 10 ثوانٍ لتهيئة الوظيفة. خلال هذه الفترة الزمنية، تم تشغيل وظائف Lambda في وحدة المعالجة المركزية لتسريع عملية التهيئة، وهي مجانية. إذا لم تتمكن وظيفة lambda من إكمال التهيئة خلال 10 ثوانٍ، فسوف تقوم Lambda بإعادة تشغيل الوظيفة، وإصدار فاتورة للتهيئة. لمساعدة الوظائف على استخدام وقت التهيئة المجاني الذي يبلغ 10 ثوانٍ وتجنب إعادة التشغيل، يدعم Lambda Web Adaptor التهيئة غير المتزامنة. عند تمكين هذه الميزة، يقوم Lambda Web Adaptor بفحص الجاهزية لمدة تصل إلى 9.8 ثانية. إذا لم يكن تطبيق الويب جاهزًا بحلول ذلك الوقت، يرسل Lambda Web Adaptor إشارة إلى خدمة Lambda تفيد بأن init قد اكتمل، ويستمر في التحقق من الاستعداد في المعالج. يتم تعطيل هذه الميزة بشكل افتراضي. قم بتمكينه عن طريق تعيين متغير البيئة AWS_LWA_ASYNC_INIT
على true
.
AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH - تخبر قيمة متغير البيئة هذا المحول ما إذا كان التطبيق يعمل ضمن مسار أساسي. على سبيل المثال، كان من الممكن أن تقوم بتكوين بوابة واجهة برمجة التطبيقات الخاصة بك بحيث تحتوي على مورد /orders/{proxy+} ومورد /catalog/{proxy+}. تتم معالجة كل مورد بواسطة وظائف Lambda منفصلة. لهذا السبب، قد لا يكون التطبيق داخل Lambda على علم بوجود المسار /orders. استخدم REMOVE_BASE_PATH لإزالة البادئة /orders عند توجيه الطلبات إلى التطبيق. الإعدادات الافتراضية لسلسلة فارغة. مثال على الخروج من SpringBoot.
AWS_LWA_ENABLE_COMPRESSION - يدعم Lambda Web Adaptor ضغط gzip لنص الاستجابة. يتم تعطيل هذه الميزة بشكل افتراضي. قم بتمكينه عن طريق تعيين متغير البيئة AWS_LWA_ENABLE_COMPRESSION
على true
. عند التمكين، سيؤدي هذا إلى ضغط الاستجابات ما لم تكن صورة وفقًا لما يحدده نوع المحتوى الذي يبدأ image
أو ما لم تكن الاستجابة أقل من 32 بايت. سيؤدي هذا أيضًا إلى ضغط استجابة البث المقسمة لـ HTTP/1.1.
AWS_LWA_INVOKE_MODE - وضع استدعاء دالة Lambda، يجب أن يتطابق هذا مع وضع استدعاء عنوان URL للوظيفة. الافتراضي هو "مخزنة". عند تكوينه كـ "response_stream"، سيقوم Lambda Web Adaptor ببث الاستجابة إلى مدونة خدمة Lambda. يرجى مراجعة FastAPI مع مثال تدفق الاستجابة.
AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS - يسمح لك بتخصيص رموز حالة HTTP التي تعتبر سليمة وأيها ليست كذلك
AWS_LWA_PASS_THROUGH_PATH - مسار لتلقي حمولات الأحداث التي تم تمريرها من مشغلات أحداث غير http. الافتراضي هو "/ الأحداث".
AWS_LWA_AUTHORIZATION_SOURCE - عند التعيين، يستبدل Lambda Web Adaptor اسم الرأس المحدد Authorization
قبل إنشاء وكيل للطلب. يعد هذا مفيدًا عند استخدام عنوان URL لوظيفة Lambda مع نوع مصادقة IAM، الذي يحتفظ برأس التفويض لمصادقة IAM، ولكنك تريد الاستمرار في استخدام رأس التفويض لتطبيقات الواجهة الخلفية الخاصة بك. يتم تعطيل هذه الميزة بشكل افتراضي.
سياق الطلب هو البيانات التعريفية التي ترسلها بوابة API إلى Lambda لطلب ما. يحتوي عادةً على معرف الطلب ووقت الطلب وapId والهوية والمصرح. تعد الهوية والمصرح مفيدًا للحصول على هوية العميل للحصول على الترخيص. يحتوي دليل مطور بوابة API على مزيد من التفاصيل هنا.
يقوم Lambda Web Adaptor بإعادة توجيه هذه المعلومات إلى تطبيق الويب في رأس Http المسمى "x-amzn-request-context". في تطبيق الويب، يمكنك استرداد قيمة رأس http هذا وإلغاء تسلسله إلى كائن JSON. قم بمراجعة Express.js في ملف Zip للتعرف على كيفية استخدامه.
سياق Lambda هو كائن يمرره Lambda إلى معالج الوظيفة. يوفر هذا الكائن معلومات حول الاستدعاء والوظيفة وبيئة التنفيذ. يمكنك العثور على قائمة كاملة بالخصائص التي يمكن الوصول إليها من خلال سياق Lambda هنا
يقوم Lambda Web Adaptor بإعادة توجيه هذه المعلومات إلى تطبيق الويب في رأس Http المسمى "x-amzn-lambda-context". في تطبيق الويب، يمكنك استرداد قيمة رأس http هذا وإلغاء تسلسله إلى كائن JSON. قم بمراجعة Express.js في ملف Zip للتعرف على كيفية استخدامه.
بالنسبة لوظيفة مسجلة بامتدادات Lambda، يقوم Lambda بتمكين مرحلة إيقاف تشغيل الوظيفة. عندما تكون خدمة Lambda على وشك إيقاف تشغيل بيئة تنفيذ Lambda، فإنها ترسل إشارة SIGTERM إلى وقت التشغيل ثم حدث SHUTDOWN إلى كل امتدادات خارجية مسجلة. يمكن للمطورين التقاط إشارة SIGTERM في وظائف lambda وتنفيذ مهام إيقاف التشغيل الرائعة. يقدم Express.js مثالاً بسيطًا. مزيد من التفاصيل في هذا الريبو.
يسمح Lambda Web Adaptor للمطورين بتطوير تطبيقات الويب محليًا باستخدام أدوات ومصححات أخطاء مألوفة: ما عليك سوى تشغيل تطبيق الويب محليًا واختباره. إذا كنت تريد محاكاة بيئة Lambda Runtime محليًا، فيمكنك استخدام AWS SAM CLI. يبدأ الأمر التالي نقطة نهاية بوابة API المحلية ويحاكي بيئة تنفيذ وقت تشغيل Lambda.
sam local start-api
يرجى ملاحظة أن sam local
يبدأ تشغيل Lambda Runtime Interface Emulator على المنفذ 8080. لذلك يجب أن يتجنب تطبيق الويب الخاص بك المنفذ 8080
إذا كنت تخطط لاستخدام sam local
.
يدعم Lambda Web Adaptor أيضًا جميع مشغلات الأحداث غير HTTP، مثل SQS وSNS وS3 وDynamoDB وKinesis وKafka وEventBridge وBedrock Agents. يقوم المحول بإعادة توجيه حمولة الحدث إلى تطبيق الويب عبر نشر http إلى مسار محدد بواسطة متغير البيئة AWS_LWA_PASS_THROUGH_PATH
. افتراضيًا، يتم تعيين هذا المسار على /events
. عند استلام حمولة الحدث من نص الطلب، يجب أن يقوم تطبيق الويب بمعالجتها وإرجاع النتائج كاستجابة JSON. يرجى مراجعة SQS Express.js وBedrock Agent FastAPI في أمثلة Zip.
هذا المشروع مستوحى من العديد من المشاريع المجتمعية.
توفر العديد من المشاريع أيضًا إمكانات مماثلة مثل الحزم/أطر العمل الخاصة باللغة.
انظر المساهمة لمزيد من المعلومات.
تم ترخيص هذا المشروع بموجب ترخيص Apache-2.0.