تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

التعرُّف على كيفية استدعاء وظائف Cloud Run التي تمت مصادقتها

1. مقدمة

نظرة عامة

وظائف Cloud Run هي حلّ خفيف الوزن للحوسبة يتيح للمطوّرين إنشاء وظائف مستقلة ذات غرض واحد يمكن تشغيلها باستخدام بروتوكول HTTPS أو الاستجابة CloudEvents بدون الحاجة إلى إدارة خادم أو بيئة وقت التشغيل. يمكنك الاطّلاع على مزيد من المعلومات حول وظائف Cloud Run في مشاركة المدونة.

هناك طريقتان رئيسيتان للتحكّم في عمليات استدعاء دوال Cloud Run: تأمين الوصول استنادًا إلى الهوية وتأمين الوصول باستخدام عناصر التحكّم في الوصول المستندة إلى الشبكة. يركز هذا الدرس التطبيقي حول الترميز على المنهج الأول ويرشدك إلى 3 سيناريوهات لتأمين الوصول استنادًا إلى الهوية لتشغيل دالة:

استخدام رمز تعريف gcloud لتشغيل دالة لأغراض التطوير والاختبار على الجهاز
انتحال هوية حساب خدمة عند التطوير والاختبار على الجهاز فقط لاستخدام بيانات الاعتماد نفسها المستخدَمة في قناة الإصدار العلني
استخدام مكتبات عملاء Google لمعالجة المصادقة مع Google Cloud APIs، مثلاً عندما تحتاج الخدمة إلى استدعاء دالة

المعلومات التي ستطّلع عليها

كيفية ضبط المصادقة على وظيفة Cloud Run والتأكّد من ضبط المصادقة بشكل صحيح
استدعاء دالة تمّت مصادقتها من بيئة تطوير محلية من خلال تقديم الرمز المميّز لهوية gcloud
كيفية إنشاء حساب خدمة ومنحه الدور المناسب لاستدعاء دالة
كيفية انتحال هوية خدمة من بيئة تطوير محلية لديها الأدوار المناسبة لاستدعاء وظيفة

2. الإعداد والمتطلبات

المتطلبات الأساسية

أن تكون مسجِّلاً الدخول إلى Cloud Console
سبق لك نشر دالة Cloud Run يتم تشغيلها من خلال HTTP. الاطّلاع على مثال على البدء السريع
(اختياري) في السيناريو الثالث، يستخدم هذا الدرس التطبيقي حول الترميز Node.js وnpm كمثال، ولكن يمكنك استخدام أيّ وقت تشغيل متوافق مع مكتبات Google Auth client.

تفعيل Cloud Shell

من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهيتها. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

من المفترض ألا تستغرق عملية توفير Cloud Shell والاتصال بها سوى بضع لحظات.

تم تحميل هذه الآلة الافتراضية بجميع أدوات التطوير اللازمة. وتوفّر هذه الشبكة دليلاً رئيسيًا دائمًا بسعة 5 غيغابايت ويتم تشغيله في Google Cloud، ما يحسّن بشكل كبير من أداء الشبكة والمصادقة. يمكن تنفيذ الكثير من عملك في هذا الدليل التعليمي للترميز، إن لم يكن كلّه، باستخدام متصفّح.

بعد الاتصال بـ Cloud Shell، من المفترض أن تظهر لك رسالة تفيد بأنّه تم مصادقة حسابك وأنّه تم ضبط المشروع على معرّف مشروعك.

نفِّذ الأمر التالي في Cloud Shell لتأكيد مصادقة حسابك:

gcloud auth list

ناتج الأمر

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

شغّل الأمر التالي في Cloud Shell للتأكد من معرفة الأمر gcloud بمشروعك:

gcloud config list project

ناتج الأمر

[core]
project = <PROJECT_ID>

إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:

gcloud config set project <PROJECT_ID>

ناتج الأمر

Updated property [core/project].

3- إنشاء دالة Cloud Run تمت مصادقتها واختبارها

يعني طلب المصادقة أنّه يجب أن يكون لدى المبدأ الذي يستدعي الدالة دور "مُشغِّل Cloud Run"، وإلا ستعرض الدالة خطأ 403 "محظور". سيوضّح لك هذا الدليل التعليمي حول الرموز البرمجية كيفية منح أدوار Invoker المناسبة لعنصر أساسي.

إعداد متغيّرات البيئة المحلية لأوامر gcloud المبسّطة

أولاً، عليك إنشاء بعض المتغيّرات في البيئة لتحسين إمكانية قراءة أوامر gcloud المستخدمة في هذا الدرس التطبيقي حول الترميز.

REGION=us-central1
PROJECT_ID=$(gcloud config get-value project)

إنشاء رمز المصدر للدالة

على الرغم من أنّ هذا الدرس التطبيقي حول الترميز يستخدم Node.js، يمكنك استخدام أي بيئة تشغيل متوافقة مع مكتبات برامج مصادقة Google.

أولاً، أنشئ دليلاً وانتقل إليه باستخدام الأمر cd.

mkdir auth-function-codelab && cd $_

ثم أنشئ ملف package.json.

touch package.json

echo '{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}
' > package.json

بعد ذلك، أنشئ ملف المصدر index.js.

touch index.js

echo 'const functions = require("@google-cloud/functions-framework");

functions.http("helloWorld", (req, res) => {
 res.send(`Hello ${req.query.name || req.body.name || "World"}!`);
});' > index.js

إنشاء الدالة التي تمت مصادقتها

في ما يلي خطوات إنشاء دالة تمت مصادقتها لبيئة تشغيلNodejs20. ومع ذلك، يمكنك استخدام أي وقت تشغيل متوافق مع مكتبات عملاء Google Auth.

FUNCTION_NAME=authenticated-function-codelab
ENTRY_POINT=helloWorld

لنشر دالة Cloud Run مباشرةً على Cloud Run، نفِّذ الأمر التالي:

gcloud beta run deploy $FUNCTION_NAME \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated

ويمكنك بعد ذلك حفظ عنوان URL للدالة كمتغيّر بيئة لاستخدامه لاحقًا.

FUNCTION_URL="$(gcloud run services describe $FUNCTION_NAME --region $REGION --format 'value(status.url)')"

إذا كنت تفضّل النشر كخدمة من الجيل الثاني من Cloud Functions، استخدِم الأمر التالي:

gcloud functions deploy nodejs-http-function \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated

وبعد ذلك يمكنك حفظ الدالة URL كمتغير بيئي لاستخدامها لاحقًا.

FUNCTION_URL="$(gcloud functions describe $FUNCTION_NAME --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

تأكَّد من أنّ الدالة تتطلّب المصادقة من خلال محاولة استدعائها كمتصل مجهول.

ستستدعي الدالة بدون مصادقة للتأكّد من ظهور خطأ 403 المتوقّع.

من سطر أوامر، شغِّل الأمر curl التالي:

curl -i $FUNCTION_URL

ستظهر لك النتيجة التالية:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>403 Forbidden</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Forbidden</h1>
<h2>Your client does not have permission to get URL <code>/</code> from this server.</h2>
<h2></h2>
</body></html>

أنت الآن جاهز للاطّلاع على 3 سيناريوهات يمكنك من خلالها استدعاء الدالة من خلال تقديم المصادقة.

4. السيناريو 1: استخدام رمز تعريف الهوية gcloud

بصفتك مطوّرًا، ستحتاج إلى طريقة لاختبار الدالة أثناء تطويرها على الجهاز. في هذا القسم، ستُجري اختبارًا سريعًا للتحقّق من مصادقة الدالة بشكل صحيح باستخدام هويتك.

تأكَّد من أنّك تمّت مصادقة حسابك باستخدام gcloud من خلال تنفيذ الأمر التالي:

gcloud auth list

من المفترض أن يظهر لك نجم بجانب هويتك النشطة، على سبيل المثال:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

يمكنك العثور على مزيد من المعلومات حول إعداد gcloud init وgcloud auth login في المستندات.

بعد ذلك، استدعِ الدالة وقم بتمريرها إلى رمز هويتك.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token)"

ستظهر لك الآن النتيجة:

Hello World!

تحديد المشاكل وحلّها

إذا ظهرت لك رسالة الخطأ "403 محظور"، تأكَّد من أنّ هويتك تحمل دور "مرسل تشغيل السحابة الإلكترونية". يمكنك استخدام وحدة تحكّم إدارة الهوية وإمكانية الوصول للتحقّق من الأدوار الممنوحة لمستخدم أساسي.

على الرغم من أنّ استخدام رمزك المميّز لإثبات الهوية هو طريقة سريعة لاختبار وظيفتك أثناء التطوير، سيحتاج المتصل بالدالة التي تمت مصادقتها إلى الأدوار المناسبة، وإلّا، سيتلقّى المتصل الخطأ "403 محظور".

ستحتاج إلى اتّباع مبدأ الحدّ الأدنى من الأذونات المميّزة من خلال الحدّ من عدد الهويات وحسابات الخدمة التي لديها أدوار لاستدعاء الوظيفة. في السيناريو التالي، ستتعرّف على كيفية إنشاء حساب خدمة جديد ومنحه الأدوار المناسبة لتشغيل الدالة.

5- السيناريو 2: انتحال هوية حساب خدمة

في هذا السيناريو، عليك انتحال هوية (أي الحصول على أذونات) حساب خدمة لاستدعاء دالة عند التطوير والاختبار على الجهاز. من خلال انتحال هوية حساب خدمة، يمكنك اختبار الدالة باستخدام بيانات الاعتماد نفسها المستخدَمة في مرحلة الإنتاج.

من خلال إجراء ذلك، لن تُثبت صحة الأدوار فحسب، بل ستلتزم أيضًا بمبدأ الحد الأدنى من الامتيازات من خلال عدم الحاجة إلى منح دور "مُشغِّل وظائف السحابة الإلكترونية" لهويات أخرى لأغراض الاختبار المحلي فقط.

لأغراض هذا الدليل التعليمي حول رموز البرامج، ستُنشئ حساب خدمة جديدًا لا يتضمّن سوى أدوار لتشغيل الدالة التي أنشأتها في هذا الدليل التعليمي.

إنشاء حساب خدمة جديد

أولاً، ستقوم بإنشاء متغيرين إضافيين للبيئة لتمثيل حسابات الخدمة المستخدمة في أوامر gcloud.

SERVICE_ACCOUNT_NAME="invoke-functions-codelab"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

بعد ذلك، عليك إنشاء حساب الخدمة.

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Cloud Run function Authentication codelab"

وامنح حساب الخدمة دور استدعاء Cloud Run:

gcloud run services add-iam-policy-binding $FUNCTION_NAME \
  --region=us-central1  \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/run.invoker'

استدعاء الدالة من خلال انتحال هوية حساب الخدمة

ولتنفيذ ذلك، ستُنتحل هوية حساب الخدمة الذي تم إنشاؤه حديثًا من خلال الحصول على الرمز المميّز للمعرِّف.

إضافة الأدوار المطلوبة لانتحال الهوية

للتنكر بصفتك حساب خدمة، يجب أن يكون لحساب المستخدم دور صانع الرموز المميّزة لحساب الخدمة (roles/iam.serviceAccountTokenCreator) لإنشاء رمز تعريف لحساب الخدمة.

يمكنك تنفيذ الأوامر التالية لمنح حساب المستخدم النشط هذا الدور:

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")

gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_ADDRESS  \
  --member user:$ACCOUNT_EMAIL \
  --role='roles/iam.serviceAccountTokenCreator'

استخدام الرمز المميّز لتعريف حساب الخدمة

انتظر بضع دقائق ريثما يتم نشر الأذونات. يمكنك الآن استدعاء الدالة من خلال تمرير الرمز المميز للمعرّف لحساب الخدمة.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token --impersonate-service-account $SERVICE_ACCOUNT_ADDRESS)"

سيظهر لك ما يلي:

WARNING: This command is using service account impersonation. All API calls will be executed as [invoke-functions-codelab@<project-id>.iam.gserviceaccount.com].

Hello World!

6- السيناريو 3: استخدام مكتبات عملاء Google

في هذا الجزء الأخير من ورشة رموز البرامج، ستشغّل خدمة صغيرة على الجهاز لإنشاء رمز تعريف لحساب خدمة، ثم ستستدعي الدالة آليًا باستخدام مكتبات برامج Google Auth وبيانات الاعتماد التلقائية للتطبيق (ADC). يمكنك الاطّلاع على مزيد من المعلومات عن مكتبات عملاء Google في قسم "شرح مكتبات العملاء" من المستندات.

من المهم استخدام أداة ربط البيانات بشكل خاص عندما تريد كتابة وظائفك واختبارها على الجهاز (مثل الكمبيوتر المحمول أو Cloud Shell أو غير ذلك) أثناء التفاعل مع موارد Google Cloud الأخرى (مثل Cloud Storage وVision API وغير ذلك). في هذا المثال، ستتعرّف على كيفية جعل خدمة تستدعي دالة أخرى تتطلّب مصادقة. لمزيد من المعلومات حول ADC والتطوير المحلي، يُرجى الاطّلاع على مشاركة المدونة كيفية تطوير دوال Cloud واختبارها محليًا | مدوّنة Google Cloud

تنفيذ الأمر gcloud لانتحال هوية حساب خدمة

يعثر ADC تلقائيًا على بيانات الاعتماد استنادًا إلى بيئة التطبيق ويستخدم بيانات الاعتماد هذه للمصادقة على واجهات برمجة تطبيقات Google Cloud. تتيح لك علامة "انتحال هوية حساب الخدمة" انتحال هوية حساب خدمة باستخدام هويته للمصادقة على Google Cloud APIs.

لانتحال هوية حساب خدمة، يمكنك تنفيذ الأمر التالي:

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

يتم الآن تنفيذ أوامر gcloud باسم حساب الخدمة هذا بدلاً من هويتك.

إنشاء خدمة وتشغيلها لاستدعاء دالة تمت مصادقتها

يحتوي كلّ وقت تشغيل على مكتبة عملاء Google Auth الخاصة به والتي يمكنك تثبيتها. يرشدك هذا الدرس التطبيقي حول الترميز إلى كيفية إنشاء تطبيق Node.js وتشغيله على جهازك.

في ما يلي خطوات استخدام Node.js:

إنشاء دليل جديد

mkdir local-dev && cd $_

إنشاء تطبيق Node.js جديد

npm init -y

تثبيت مكتبة برامج Google Auth

npm install google-auth-library

إنشاء ملف index.js
استرجع عنوان URL لدالة Cloud Run التي ستضيفها إلى الرمز البرمجي في الخطوة التالية.

echo $FUNCTION_URL

أضِف الرمز التالي إلى index.js. تأكَّد من تغيير متغيّر targetالجمهور إلى عنوان URL لدالة Cloud Run.

ملف index.js

// Cloud Functions uses your function's url as the `targetAudience` value

const targetAudience = '<YOUR-CLOUD-RUN-FUNCTION-URL>';

// For Cloud Functions, endpoint(`url`) and `targetAudience` should be equal

const url = targetAudience;

const { GoogleAuth } = require('google-auth-library');
const auth = new GoogleAuth();

async function request() {
    console.info(`request ${url} with target audience ${targetAudience}`);

    // this call retrieves the ID token for the impersonated service account
    const client = await auth.getIdTokenClient(targetAudience);

    const res = await client.request({ url });
    console.info(res.data);
}

request().catch(err => {
    console.error(err.message);
    process.exitCode = 1;
});

تشغيل التطبيق

node index.js

من المفترض أن يظهر لك الردّ "مرحبًا بالجميع".

تحديد المشاكل وحلّها

إذا ظهرت لك رسالة الخطأ "تم رفض الإذن iam.serviceAccounts.getOpenIdToken" في المورد (أو قد لا يكون متوفّرًا)، يُرجى الانتظار بضع دقائق حتى يتم نشر دور "صانع رمز رمز حساب الخدمة".

إذا ظهر لك الخطأ "تعذّر جلب رمز التعريف في هذه البيئة، استخدِم GCE أو اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على ملف JSON لبيانات اعتماد حساب الخدمة"، قد يكون السبب أنّك نسيت تنفيذ الأمر

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

7- تهانينا!

تهانينا على إكمال دورة codelab.

ننصحك بمراجعة المستندات حول كيفية تأمين وظائف Cloud Run.

ننصحك أيضًا بقراءة مشاركة المدونة هذه حول التطوير على الجهاز المحلي باستخدام دوال Cloud Run للتعرّف على كيفية تطوير واختبار وظيفة Cloud Run في بيئة المطوّر المحلية.

المواضيع التي تناولناها

كيفية ضبط المصادقة في إحدى وظائف Cloud Run والتأكّد من ضبط المصادقة بشكلٍ صحيح
استدعاء دالة تمّت مصادقتها من بيئة تطوير محلية من خلال تقديم الرمز المميّز لهوية gcloud
كيفية إنشاء حساب خدمة ومنحه الدور المناسب لاستدعاء دالة
كيفية انتحال هوية خدمة من بيئة تطوير محلية لديها الأدوار المناسبة لاستدعاء وظيفة

8. تَنظيم

لتجنُّب الرسوم غير المقصودة (على سبيل المثال، إذا تمّ استدعاء دالة Cloud هذه بدون قصد أكثر من المساحة المخصّصة لك شهريًا لاستدعاء دالة Cloud Run في الفئة المجانية)، يمكنك إما حذف دالة Cloud أو حذف المشروع الذي أنشأته في الخطوة 2.

لإيقاف انتحال هوية حساب الخدمة، يمكنك إعادة تسجيل الدخول باستخدام هويتك:

gcloud auth application-default login

لحذف دالة التشغيل في السحابة الإلكترونية، انتقِل إلى وحدة التحكّم في Cloud Run لوظيفة Cloud على https://console.cloud.google.com/functions/. تأكَّد من أنّ المشروع الذي أنشأته في الخطوة الثانية هو المشروع المختار حاليًا.

اختَر my-authenticated-function التي تم نشرها سابقًا. بعد ذلك، انقر على حذف.

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager واختيار المشروع الذي أنشأته في الخطوة 2 ثم اختيار "حذف". في حال حذف المشروع، عليك تغيير المشاريع في حزمة تطوير البرامج (SDK) من Cloud. يمكنك عرض قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.

التعرُّف على كيفية استدعاء وظائف Cloud Run التي تمت مصادقتها تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

1. مقدمة

نظرة عامة

المعلومات التي ستطّلع عليها

2. الإعداد والمتطلبات

المتطلبات الأساسية

تفعيل Cloud Shell

3- إنشاء دالة Cloud Run تمت مصادقتها واختبارها

إعداد متغيّرات البيئة المحلية لأوامر gcloud المبسّطة

إنشاء رمز المصدر للدالة

إنشاء الدالة التي تمت مصادقتها

تأكَّد من أنّ الدالة تتطلّب المصادقة من خلال محاولة استدعائها كمتصل مجهول.

4. السيناريو 1: استخدام رمز تعريف الهوية gcloud

تحديد المشاكل وحلّها

5- السيناريو 2: انتحال هوية حساب خدمة

إنشاء حساب خدمة جديد

استدعاء الدالة من خلال انتحال هوية حساب الخدمة

إضافة الأدوار المطلوبة لانتحال الهوية

استخدام الرمز المميّز لتعريف حساب الخدمة

6- السيناريو 3: استخدام مكتبات عملاء Google

تنفيذ الأمر gcloud لانتحال هوية حساب خدمة

إنشاء خدمة وتشغيلها لاستدعاء دالة تمت مصادقتها

ملف index.js

تحديد المشاكل وحلّها

7- تهانينا!

المواضيع التي تناولناها

8. تَنظيم

التعرُّف على كيفية استدعاء وظائف Cloud Run التي تمت مصادقتها