راه‌اندازی پردازش رویداد از فضای ذخیره‌سازی ابری با استفاده از عملکردهای Eventarc و Cloud Run

۱. مرور کلی

در این آزمایش، شما یاد خواهید گرفت که چگونه از رویدادهای مخزن ذخیره‌سازی ابری و Eventarc برای شروع پردازش رویداد استفاده کنید. شما از توابع Cloud Run برای تجزیه و تحلیل داده‌ها و پردازش تصاویر استفاده خواهید کرد. این تابع از API Vision گوگل استفاده می‌کند و تصویر حاصل را دوباره در مخزن ذخیره‌سازی ابری ذخیره می‌کند.

۴۲۴۷۹۰۱۳ac38648.png

آنچه یاد خواهید گرفت

نحوه ساخت خط لوله پردازش تصویر.

  • پیکربندی مخازن ذخیره‌سازی
  • ایجاد توابع Cloud Run برای خواندن و نوشتن اشیاء در Cloud Storage
  • یک تریگر Eventarc را مستقر کنید
  • ادغام رابط برنامه‌نویسی کاربردی بینایی برای تشخیص تصاویر غذا
  • راه حل نهایی را آزمایش و اعتبارسنجی کنید

پیش‌نیازها

  • این آزمایشگاه فرض را بر آشنایی با محیط‌های Cloud Console و Shell می‌گذارد.
  • تجربه قبلی در زمینه ذخیره‌سازی ابری، عملکردهای Cloud Run یا رابط برنامه‌نویسی کاربردی Vision مفید است اما الزامی نیست.

۲. تنظیمات و الزامات

راه‌اندازی پروژه ابری

  1. وارد کنسول گوگل کلود شوید و یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. اگر از قبل حساب جیمیل یا گوگل ورک اسپیس ندارید، باید یکی ایجاد کنید .

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • نام پروژه، نام نمایشی برای شرکت‌کنندگان این پروژه است. این یک رشته کاراکتری است که توسط APIهای گوگل استفاده نمی‌شود. شما همیشه می‌توانید آن را به‌روزرسانی کنید.
  • شناسه پروژه در تمام پروژه‌های گوگل کلود منحصر به فرد است و تغییرناپذیر است (پس از تنظیم، قابل تغییر نیست). کنسول کلود به طور خودکار یک رشته منحصر به فرد تولید می‌کند؛ معمولاً برای شما مهم نیست که چه باشد. در اکثر آزمایشگاه‌های کد، باید شناسه پروژه خود را (که معمولاً با عنوان PROJECT_ID شناخته می‌شود) ارجاع دهید. اگر شناسه تولید شده را دوست ندارید، می‌توانید یک شناسه تصادفی دیگر ایجاد کنید. به عنوان یک جایگزین، می‌توانید شناسه خودتان را امتحان کنید و ببینید که آیا در دسترس است یا خیر. پس از این مرحله قابل تغییر نیست و در طول پروژه باقی می‌ماند.
  • برای اطلاع شما، یک مقدار سوم، شماره پروژه ، وجود دارد که برخی از APIها از آن استفاده می‌کنند. برای کسب اطلاعات بیشتر در مورد هر سه این مقادیر، به مستندات مراجعه کنید.
  1. در مرحله بعد، برای استفاده از منابع/API های ابری، باید پرداخت صورتحساب را در کنسول ابری فعال کنید . اجرای این آزمایشگاه کد هزینه زیادی نخواهد داشت، اگر اصلاً هزینه‌ای داشته باشد. برای خاموش کردن منابع به منظور جلوگیری از پرداخت صورتحساب پس از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری هستند.

فعال کردن پوسته ابری

با کلیک روی آیکون سمت راست نوار جستجو، Cloud Shell را فعال کنید.

b02c63d9c7632ef8.png

تنظیمات محیط

  1. با اجرای دستورات زیر در ترمینال Cloud Shell، یک پروژه و متغیرهای محیطی مرتبط با منابع ایجاد کنید. 
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET_NAME=menu-item-uploads-$PROJECT_ID
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")
  1. فعال کردن API های مورد نیاز برای آزمایشگاه 
gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet
  1. مخزن را کلون کنید 
git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

۳. پیکربندی مخازن ذخیره‌سازی ابری

ایجاد سطل‌های ذخیره‌سازی

برای پردازش تصویر خود، سطل‌های ذخیره‌سازی ابری آپلود و تصاویر بندانگشتی ایجاد کنید.

برای ایجاد دو سطل از دستور gsutil mb و یک نام منحصر به فرد استفاده کنید:

  1. سطل آپلود که تصاویر ابتدا در آن آپلود می‌شوند
  2. سطل تصاویر کوچک برای ذخیره تصاویر کوچک تولید شده

ایجاد یک باکت برای آپلود تصاویر جدید:

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

خروجی مثال:

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

یک سطل برای ذخیره تصاویر کوچک تولید شده ایجاد کنید:

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

خروجی مثال:

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

به‌روزرسانی مجوزهای باکت

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

از دستور gsutil iam ch برای دادن مجوز خواندن و نوشتن اشیاء در سطل خود استفاده کنید:

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

خروجی مثال

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

۴. پیکربندی حساب‌های سرویس

برای پردازش ریز عکس‌ها، یک حساب سرویس سفارشی برای Cloud Function ایجاد کنید: 

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

به نقش artifactregistry.reader اجازه دهید عملیات خواندن را از رجیستری Artifact انجام دهد: 

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

نقش storage.objectCreator را اعطا کنید تا امکان ذخیره تصاویر تولید شده در سطل تصاویر کوچک فراهم شود: 

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

نقش run.invoker را اعطا کنید تا امکان فراخوانی سرویس Cloud Run فراهم شود: 

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

نقش eventarc.eventReceiver را اعطا کنید تا امکان دریافت رویدادها از ارائه‌دهندگان فراهم شود: 

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/eventarc.eventReceiver"

نقش pubsub.publisher را به حساب سرویس Cloud Storage اعطا کنید. این به حساب سرویس اجازه می‌دهد تا هنگام آپلود تصاویر در سطل، رویدادها را منتشر کند. 

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

۵. بررسی اجمالی عملکرد پردازش تصویر

یک تابع برای دانلود یک تصویر از فضای ذخیره‌سازی ابری، تغییر اندازه تصویر و آپلود مجدد تصویر به فضای ذخیره‌سازی ابری ایجاد کنید. این تابع، Vision API را برای اختصاص یک برچسب توضیحات به تصویر فراخوانی می‌کند. تابع برچسب توضیحات را بررسی می‌کند. اگر برچسب، تصویر را به عنوان "غذا" شناسایی کند، رویدادی به سرویس منو ارسال می‌شود تا تصویر و تصویر بندانگشتی آیتم منو را به‌روزرسانی کند.

4c3c3b758dba6a9f.png

فعال کردن یک تابع

عملکردهای ذخیره‌سازی ابری مبتنی بر اعلان‌های Pub/Sub از ذخیره‌سازی ابری هستند و از انواع رویدادهای مشابه پشتیبانی می‌کنند:

در این آزمایش، هنگامی که یک شیء در فضای ذخیره‌سازی ابری نهایی می‌شود، یک تابع را مستقر و فعال خواهید کرد.

نهایی کردن شیء

رویدادهای نهایی‌سازی شیء زمانی فعال می‌شوند که "نوشتن" یک شیء ذخیره‌سازی ابری با موفقیت نهایی شود. به طور خاص، این بدان معناست که ایجاد یک شیء جدید یا بازنویسی یک شیء موجود، این رویداد را فعال می‌کند. عملیات بایگانی و به‌روزرسانی فراداده توسط این رویداد نادیده گرفته می‌شوند.

۶. ادغام فضای ذخیره‌سازی ابری

فضای ذخیره‌سازی ابری (Cloud Storage) سرویسی برای ذخیره اشیاء شما در فضای ابری گوگل (Google Cloud) است. یک شیء، قطعه داده‌ای تغییرناپذیر است که از یک فایل با هر فرمتی تشکیل شده است. شما اشیاء را در کانتینرهایی به نام سطل (Bucket) ذخیره می‌کنید. همه سطل‌ها به یک پروژه مرتبط هستند و می‌توانید پروژه‌های خود را تحت یک سازمان گروه‌بندی کنید. کتابخانه‌ها و APIهای کلاینت ، ادغام با فضای ذخیره‌سازی ابری را ممکن می‌سازند.

در این آزمایش، شما از کتابخانه کلاینت برای خواندن و نوشتن اشیاء در فضای ذخیره‌سازی ابری استفاده خواهید کرد.

نصب کتابخانه کلاینت

کتابخانه‌های کلاینت ابری در بسیاری از زبان‌های برنامه‌نویسی محبوب موجود هستند. برای شروع استفاده از کتابخانه‌ها، باید کتابخانه کلاینت را نصب کنید.

استفاده از کتابخانه کلاینت

جزئیات پیاده‌سازی تا حد زیادی به زبان برنامه‌نویسی بستگی دارد. برای استفاده از کتابخانه کلاینت در برنامه خود، اولین قدم وارد کردن وابستگی‌های Cloud Storage است. برای مثال، در پروژه Node.js، importها در فایل package.json اضافه می‌شوند. قطعه کد زیر، اطلاعیه مربوط به فایل package.json این آزمایشگاه را نشان می‌دهد.

بسته.json 

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

ثبت یک فراخوانی CloudEvent

یک فراخوانی CloudEvent با Functions Framework ثبت کنید که هنگام آپلود تصویر جدید در سطل، توسط Cloud Storage فعال می‌شود.

ایندکس.js 

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

ایجاد یک شیء مرجع ذخیره‌سازی

پس از وارد کردن کتابخانه‌های کلاینت، باید یک کلاینت ذخیره‌سازی جدید و باکت‌هایی که برنامه شما با آنها تعامل خواهد داشت، ایجاد کنید.

ایندکس.js 

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

دانلود اشیاء ذخیره‌سازی ابری

ایندکس.js 

await bucket.file(file.name).download({
            destination: originalFile
        });

اشیاء را در فضای ذخیره‌سازی ابری بارگذاری کنید

شما می‌توانید درخواست‌های آپلود را به سه روش به فضای ذخیره‌سازی ابری ارسال کنید: درخواست تکی، قابلیت از سرگیری یا آپلود چندبخشی XML API. برای آپلودهای بزرگتر یا آپلودهای جریانی، از آپلودهای از سرگیری استفاده کنید. با XML API، فایل‌ها به صورت قطعات آپلود شده و به عنوان یک شیء واحد جمع‌آوری می‌شوند. برای اشیاء کوچکتر، از آپلودهای تک درخواستی استفاده کنید.

کد زیر با استفاده از آپلود تک درخواستی، یک تصویر را در فضای ابری آپلود می‌کند.

ایندکس.js 

const thumbnailImage = await thumbBucket.upload(thumbFile);

۷. ادغام رابط برنامه‌نویسی کاربردی ویژن

Cloud Vision به توسعه‌دهندگان اجازه می‌دهد تا به راحتی ویژگی‌های تشخیص بینایی، از جمله برچسب‌گذاری تصویر، تشخیص چهره و نقاط دیدنی، تشخیص کاراکتر نوری (OCR) و برچسب‌گذاری محتوای صریح را در برنامه‌ها ادغام کنند.

نصب کتابخانه کلاینت

کتابخانه‌های کلاینت ابری در بسیاری از زبان‌های برنامه‌نویسی محبوب موجود هستند. برای شروع استفاده از کتابخانه‌ها، باید کتابخانه کلاینت را نصب کنید.

ایجاد یک کلاینت حاشیه‌نویس تصویر

برای دسترسی به APIهای گوگل با استفاده از SDKهای رسمی کلاینت، شما یک شیء سرویس بر اساس سند کشف API ایجاد می‌کنید که API را برای SDK توصیف می‌کند. شما باید آن را با استفاده از اعتبارنامه‌های خود از سرویس کشف Vision API دریافت کنید.

ایندکس.js 

const client = new vision.ImageAnnotatorClient();

ساخت یک درخواست Vision API

رابط برنامه‌نویسی کاربردی Vision می‌تواند با ارسال محتویات فایل تصویر به صورت یک رشته کدگذاری شده base64 در بدنه درخواست شما، تشخیص ویژگی را روی یک فایل تصویر انجام دهد.

برای ایجاد یک درخواست با استفاده از منبع تصاویر برای حاشیه‌نویسی تصویر خود، یک درخواست به این API به شکل یک شیء با یک لیست درخواست‌ها است. هر آیتم در این لیست شامل دو بخش اطلاعات است:

  • داده‌های تصویر کدگذاری شده با base64
  • فهرستی از ویژگی‌هایی که می‌خواهید در مورد آن تصویر حاشیه‌نویسی کنید.

ایندکس.js 

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

۸. توابع Cloud Run را مستقر کنید

این سرویس تغییر اندازه تصویر بخشی از سیستم بزرگتر Cymbal Eats است. در این بخش، فقط اجزای مربوط به ویژگی پردازش تصویر را مستقر خواهید کرد. نصب کامل شامل یک رابط کاربری برای آپلود تصویر و یک درخواست پایین‌دستی برای ذخیره فراداده‌های حاصل است. این قابلیت‌ها به عنوان بخشی از این آزمایش نصب نمی‌شوند.

اجزای زیر در طول استقرار تابع ایجاد خواهند شد:

  • عملکردهای Cloud Run
  • ماشه Eventarc
  • انتشار/زیرموضوع و اشتراک

در ترمینال cloudshell، دستور زیر را اجرا کنید تا توابع Cloud Run با یک trigger bucket در menu-item-uploads-$PROJECT_ID مستقر شوند:

برای استقرار مستقیم توابع Cloud Run روی Cloud Run، ابتدا تابع را مستقر کرده و سپس یک تریگر برای آن ایجاد می‌کنید.

توابع اجرای ابری را مستقر کنید: 

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
--set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

خروجی مثال: 

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

تریگر را ایجاد کنید: 

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

خروجی مثال: 

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

اگر به دلیل مشکل مجوز، استقرار تریگر با شکست مواجه شد - لطفاً منتظر بمانید تا تغییرات IAM از مرحله قبل منتشر شود. معمولاً ۱-۲ دقیقه طول می‌کشد، و سپس دوباره برای استقرار تلاش کنید.

مثال خروجی خطا: 

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...]

در کنسول Cloud، سرویس Cloud Run که برای این تابع ایجاد شده است را بررسی کنید:

546c5c951cf0f2f.png

در کنسول Cloud، تریگر Eventarc که برای این تابع ایجاد شده است را بررسی کنید:

dec11309016b09ac.png

در کنسول ابری، موضوع انتشار/زیرموضوع و اشتراکی که برای تریگر Eventarc ایجاد شده‌اند را بررسی کنید:

affe089c39ae1465.png

a4c41ede2af300db.png

۹. راهکار را از ابتدا تا انتها آزمایش و اعتبارسنجی کنید

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

بارگذاری تصویر

ab7b43f876f9c3a9.jpeg

  1. این تصویر را در دستگاه محلی خود ذخیره کنید
  2. تغییر نام فایل 1.jpg
  3. کنسول ذخیره‌سازی ابری را باز کنید
  4. روی سطل menu-item-uploads-... کلیک کنید
  5. روی آپلود فایل‌ها کلیک کنید
  6. فایل 1.jpg را در حافظه آپلود کنید
  7. در کنسول ابری، به Cloud Run بروید
  8. روی بندانگشتی‌های فرآیند کلیک کنید
  9. روی برگه LOGS کلیک کنید

fca8e4bafbdf135d.png

  1. به بخش ذخیره‌سازی ابری menu-item-thumbnails-$PROJECT_ID بروید.
  2. تأیید کنید که تصویر کوچک در بخش تصاویر کوچک ایجاد شده است

۱b6dee72a1fde681.png

آپلود تصویر غیر غذایی

برای تأیید صحت عملکرد تابع، تصویری را بارگذاری خواهید کرد که حاوی شیء‌ای نباشد که به عنوان یک کالای «غذا» طبقه‌بندی شود.

c76dd525765f66a6.jpeg

  1. این تصویر را در دستگاه محلی خود ذخیره کنید
  2. تغییر نام فایل 2.jpg
  3. کنسول ذخیره‌سازی ابری را باز کنید
  4. روی سطل menu-item-uploads-... کلیک کنید
  5. روی آپلود فایل‌ها کلیک کنید
  6. فایل 2.jpg را در حافظه آپلود کنید
  7. در کنسول ابری، به Cloud Run بروید
  8. روی بندانگشتی‌های فرآیند کلیک کنید
  9. روی برگه LOGS کلیک کنید

18b1e30ee78d3955.png

۱۰. تبریک می‌گویم!

تبریک می‌گویم، آزمایشگاه را تمام کردید!

قدم بعدی چیست؟

سایر آزمایشگاه‌های کد Cymbal Eats را کاوش کنید:

تمیز کردن

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

حذف پروژه

ساده‌ترین راه برای حذف هزینه‌ها، حذف پروژه‌ای است که برای آموزش ایجاد کرده‌اید.