الصورة اليومية: التمرين المعملي 1 — تخزين الصور وتحليلها (لغة Java الأصلية)

1. نظرة عامة

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

المُعطيات

• تخزين في السحابة الإلكترونية
• Cloud Run
• واجهة برمجة تطبيقات Cloud Vision
• Cloud Firestore

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

إعداد بيئة ذاتية

1. سجِّل الدخول إلى Google Cloud Console وأنشئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

• اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
• يكون رقم تعريف المشروع فريدًا في جميع مشاريع Google Cloud وغير قابل للتغيير (لا يمكن تغييره بعد تحديده). تنشئ Cloud Console سلسلة فريدة تلقائيًا. فعادةً لا تهتم بما هو. في معظم الدروس التطبيقية حول الترميز، يجب الإشارة إلى رقم تعريف المشروع (الذي يتم تحديده عادةً على أنّه PROJECT_ID). وإذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. ويمكنك بدلاً من ذلك تجربة طلبك الخاص ومعرفة ما إذا كان متاحًا. ولا يمكن تغييره بعد هذه الخطوة ويبقى طوال مدة المشروع.
• لمعلوماتك، هناك قيمة ثالثة، وهي رقم المشروع، الذي تستخدمه بعض واجهات برمجة التطبيقات. اطّلِع على مزيد من المعلومات حول هذه القيم الثلاث في المستندات.

تنبيه: يكون رقم تعريف المشروع فريدًا عالميًا ولا يمكن لأي شخص آخر استخدامه بعد اختياره. أنت المستخدم الوحيد لرقم التعريف هذا. لا يمكن استخدام رقم التعريف مرة أخرى، حتى في حال حذف مشروع.

ملاحظة: إذا كنت تستخدم حساب Gmail، يمكنك ترك الموقع الجغرافي التلقائي معيّنًا على بدون مؤسسة. إذا كنت تستخدم حسابًا على Google Workspace، اختَر موقعًا جغرافيًا يناسب مؤسستك.

2. بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام الموارد/واجهات برمجة التطبيقات في Cloud. لن يؤدي إكمال هذا الدرس التطبيقي حول الترميز إلى فرض أي تكاليف، إن وُجدت. لإيقاف تشغيل الموارد لتجنب تحمُّل الفواتير إلى ما هو أبعد من هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يكون مستخدمو Google Cloud الجدد مؤهَّلون للانضمام إلى برنامج فترة تجريبية مجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

مع أنّه يمكن إدارة Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي Google Cloud Shell، وهي بيئة سطر أوامر يتم تشغيلها في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات العلوي الأيسر:

من المفترَض أن تستغرق عملية إدارة الحسابات والاتصال بالبيئة بضع لحظات فقط. عند الانتهاء، من المفترض أن يظهر لك شيء مثل هذا:

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

3- تفعيل واجهات برمجة التطبيقات

ستستخدم في هذا التمرين المعملي Cloud Functions وVision API، ولكن يجب تفعيلها أولاً في Cloud Console أو باستخدام gcloud.

لتفعيل Vision API في Cloud Console، ابحث عن Cloud Vision API في شريط البحث:

ستنتقل إلى صفحة Cloud Vision API:

انقر على الزر ENABLE.

بدلاً من ذلك، يمكنك أيضًا تفعيلها في Cloud Shell باستخدام أداة سطر الأوامر gcloud.

داخل Cloud Shell، شغِّل الأمر التالي:

gcloud services enable vision.googleapis.com

من المفترض أن يتم الانتهاء من العملية بنجاح:

Operation "operations/acf.12dba18b-106f-4fd2-942d-fea80ecc5c1c" finished successfully.

تفعيل Cloud Run وCloud Build أيضًا:

gcloud services enable cloudbuild.googleapis.com \
  run.googleapis.com

4. إنشاء الحزمة (وحدة التحكّم)

يمكنك إنشاء حزمة تخزين للصور. ويمكنك إجراء ذلك من وحدة تحكُّم Google Cloud Platform ( console.cloud.google.com) أو باستخدام أداة سطر الأوامر gsutil من Cloud Shell أو بيئة التطوير المحلية.

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

الانتقال إلى مساحة التخزين

من "الهامبرغر" (⇧)، انتقِل إلى صفحة "Storage".

تسمية الحزمة

انقر على الزر CREATE BUCKET.

ملاحظة: يجب إنشاء اسم حزمة فريد عالميًا (هنا: uploaded-pictures، ولكن سيكون عليك اختيار اسم فريد عام).

استخدِم uploaded-pictures كبادئة، وأضِف رقم تعريف مشروعك كلاحقة. إذا كان رقم تعريف مشروعك هو my-project، يمكنك استدعاء الحزمة uploaded-pictures-my-project، وهي الصيغة المستخدمة في منهج سطر الأوامر في القسم التالي.

انقر على CONTINUE.

اختيار موقع جغرافي

يمكنك إنشاء حزمة متعددة المناطق في المنطقة التي تختارها (هنا Europe).

ملاحظة: يجب أن نستخدم المنطقة نفسها كمنطقة سنستخدمها في الدروس التطبيقية اللاحقة لمواردنا الأخرى (Cloud Functions وApp Engine وCloud Run وغيرها) لتحقيق أفضل أداء وتجنُّب أي تكاليف إضافية للدخول أو الخروج.

انقر على CONTINUE.

اختيار فئة التخزين التلقائية

اختَر فئة تخزين تبلغ Standard لبياناتك.

انقر على CONTINUE.

ضبط التحكّم في الوصول

نظرًا لأنك ستعمل على صور يمكن للجميع الوصول إليها، فأنت تريد أن يكون لجميع صورنا المخزنة في هذه الحزمة عنصر التحكم نفسه في الوصول.

حدِّد خيار التحكّم في الوصول إلى Uniform.

انقر على CONTINUE.

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

الإبقاء على الإعدادات التلقائية (Google-managed key)، لأنّك لن تستخدم مفاتيح التشفير الخاصة بك.)

انقر على CREATE لإكمال عملية إنشاء الحزمة.

إضافة كل المستخدمين كعارض لمساحة التخزين

الانتقال إلى علامة التبويب "Permissions":

يمكنك إضافة عضو allUsers إلى الحزمة، مع دور Storage > Storage Object Viewer، على النحو التالي:

انقر على SAVE.

5- إنشاء الحزمة (gsutil)

ملاحظة: إذا سبق لك إنشاء الحزمة من وحدة التحكّم في الخطوة السابقة، يمكنك تخطّي هذه الخطوة.

يمكنك أيضًا استخدام أداة سطر الأوامر gsutil في Cloud Shell لإنشاء الحِزم.

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

مثلاً:

export BUCKET_PICTURES=uploaded-pictures-${GOOGLE_CLOUD_PROJECT}

إنشاء منطقة عادية متعددة المناطق في أوروبا:

gsutil mb -l EU gs://${BUCKET_PICTURES}

تأكَّد من أنّ مستوى الوصول الموحّد على مستوى الحزمة:

gsutil uniformbucketlevelaccess set on gs://${BUCKET_PICTURES}

جعل الحزمة عامة:

gsutil iam ch allUsers:objectViewer gs://${BUCKET_PICTURES}

إذا انتقلت إلى القسم Cloud Storage في وحدة التحكّم، يُفترض أن تكون لديك حزمة uploaded-pictures علنية:

اختبِر قدرتك على تحميل الصور إلى الحزمة وأن الصور المُحمَّلة متاحة للجميع، كما هو موضَّح في الخطوة السابقة.

6- اختبار إمكانية الوصول العلني إلى الحزمة

بالعودة إلى متصفّح التخزين، ستظهر الحزمة في القائمة مع عرض الخيار "علنية". الوصول (بما في ذلك علامة تحذيرية تذكِّرك بأنّ أي مستخدم لديه إذن الوصول إلى محتوى هذه الحزمة)

حزمتك جاهزة الآن لاستلام الصور.

عند النقر على اسم الحزمة، ستظهر تفاصيل الحزمة.

من هنا، يمكنك تجربة الزر "Upload files" لاختبار إمكانية إضافة صورة إلى الحزمة. ستطلب منك نافذة منتقي الملفات المنبثقة تحديد ملف. بعد اختيار الملف، سيتم تحميله إلى حزمتك، وستظهر لك مرة أخرى إذن وصول "public" الذي تمت إحالته تلقائيًا إلى هذا الملف الجديد.

على تصنيف الوصول Public، سيظهر لك أيضًا رمز رابط صغير. عند النقر عليها، سينتقل المتصفح إلى عنوان URL العام لتلك الصورة، والذي سيكون بالشكل التالي:

https://storage.googleapis.com/BUCKET_NAME/PICTURE_FILE.png

بما أنّ BUCKET_NAME هو الاسم الفريد العالمي الذي اخترته لحزمتك، ثم اسم ملف صورتك.

بالنقر على مربع الاختيار الموجود على طول اسم الصورة، سيتم تفعيل الزر DELETE، ويمكنك حذف هذه الصورة الأولى.

7. إعداد قاعدة البيانات

ستخزن معلومات حول الصورة المقدّمة من Vision API في قاعدة بيانات Cloud Firestore، وهي قاعدة بيانات مستندات NoSQL سريعة ومُدارة بالكامل وبدون خادم. يمكنك إعداد قاعدة البيانات بالانتقال إلى القسم Firestore في Cloud Console:

يتوفّر خياران: Native mode أو Datastore mode. استخدم الوضع الأصلي، الذي يوفر ميزات إضافية مثل إمكانية الاستخدام بلا اتصال بالإنترنت والمزامنة في الوقت الفعلي.

انقر على SELECT NATIVE MODE.

اختَر منطقة متعددة (هنا في أوروبا، ولكن يُفضَّل أن تكون المنطقة نفسها على الأقل تكون الوظيفة وحزمة التخزين).

انقر على الزر CREATE DATABASE.

بعد إنشاء قاعدة البيانات، من المفترض أن يظهر لك ما يلي:

يمكنك إنشاء مجموعة جديدة بالنقر على الزر + START COLLECTION.

تسمية مجموعة "pictures".

لست بحاجة إلى إنشاء مستند. ستضيفها آليًا حيث يتم تخزين الصور الجديدة في Cloud Storage وتحليلها من خلال واجهة برمجة تطبيقات Vision.

انقر على Save.

ينشئ Firestore أول مستند افتراضي في المجموعة التي تم إنشاؤها حديثًا، ويمكنك حذف هذا المستند بأمان لأنه لا يحتوي على أي معلومات مفيدة:

ستحتوي المستندات التي سيتم إنشاؤها آليًا في مجموعتنا على 4 حقول:

• name (سلسلة): اسم ملف الصورة التي تم تحميلها، وهو أيضًا مفتاح المستند
• labels (مصفوفة من السلاسل): تصنيفات العناصر المعروفة بواسطة Vision API
• color (سلسلة): رمز اللون السداسي العشري للون السائد (مثل #ab12ef)
• CREATE (التاريخ): الطابع الزمني لوقت تخزين البيانات الوصفية لهذه الصورة
• الصورة المصغّرة (قيمة منطقية): حقل اختياري يتم عرضه ويكون صحيحًا إذا تم إنشاء صورة مصغّرة لهذه الصورة

بينما سنبحث في Firestore للعثور على الصور التي تحتوي على صور مصغرة متاحة، وسنقوم بالفرز حسب تاريخ الإنشاء، سنحتاج إلى إنشاء فهرس بحث.

يمكنك إنشاء الفهرس باستخدام الأمر التالي في Cloud Shell:

gcloud firestore indexes composite create \
  --collection-group=pictures \
  --field-config field-path=thumbnail,order=descending \
  --field-config field-path=created,order=descending

أو يمكنك أيضًا إجراء ذلك من Cloud Console من خلال النقر على Indexes في عمود التنقّل على اليمين، ثم إنشاء فهرس مركب كما هو موضّح أدناه:

انقر على Create. قد يستغرق إنشاء الفهرس بضع دقائق.

8. استنساخ الرمز

استنسِخ الرمز إذا لم يسبق لك إجراء ذلك في التمرين المعملي السابق للرموز:

git clone https://github.com/GoogleCloudPlatform/serverless-photosharing-workshop

يمكنك بعد ذلك الانتقال إلى الدليل الذي يحتوي على الخدمة لبدء إنشاء التمرين المعملي:

cd serverless-photosharing-workshop/services/image-analysis/java

وسيكون لديك تنسيق الملفات التالي للخدمة:

9. التعرّف على رمز الخدمة

عليك أن تبدأ بإلقاء نظرة على كيفية تفعيل مكتبات برامج Java في pom.xml باستخدام BOM:

أولاً، افتح ملف pom.xml الذي يعرض اعتماديات تطبيق Java، نركّز على استخدام واجهات برمجة تطبيقات Vision وCloud Storage وFirestore.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0-M3</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>services</groupId>
        <artifactId>image-analysis</artifactId>
        <version>0.0.1</version>
        <name>image-analysis</name>
        <description>Spring App for Image Analysis</description>
    <properties>
        <java.version>17</java.version>
        <maven.compiler.target>17</maven.compiler.target>
        <maven.compiler.source>17</maven.compiler.source>        
        <spring-cloud.version>2023.0.0-M2</spring-cloud.version>
        <testcontainers.version>1.19.1</testcontainers.version>
    </properties>
...
  <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>libraries-bom</artifactId>
            <version>26.24.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
  </dependencyManagement>
— 
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
                <dependency>
                        <groupId>org.springframework.cloud</groupId>
                        <artifactId>spring-cloud-function-web</artifactId>
                </dependency>
        <dependency>
            <groupId>com.google.cloud.functions</groupId>
            <artifactId>functions-framework-api</artifactId>
            <version>1.1.0</version>
            <type>jar</type>
        </dependency>
        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>google-cloud-firestore</artifactId>
        </dependency>
        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>google-cloud-vision</artifactId>
        </dependency>
        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>google-cloud-storage</artifactId>
        </dependency>        

ملاحظة: ستجد معلومات عن مكتبات برامج Java في مكتبات واجهة برمجة التطبيقات.

ملاحظة: تتم استضافة الرمز على GitHub أيضًا، إذا كنت تريد نسخ رمز Java ولصقه من هناك بدلاً من ذلك

يتم تنفيذ الوظيفة في الفئة EventController. في كل مرة يتم فيها تحميل صورة جديدة إلى الحزمة، ستتلقّى الخدمة إشعارًا بمعالجتها:

@RestController
public class EventController {
  private static final Logger logger = Logger.getLogger(EventController.class.getName());
    
  private static final List<String> requiredFields = Arrays.asList("ce-id", "ce-source", "ce-type", "ce-specversion");

  @RequestMapping(value = "/", method = RequestMethod.POST)
  public ResponseEntity<String> receiveMessage(
    @RequestBody Map<String, Object> body, @RequestHeader Map<String, String> headers) throws IOException, InterruptedException, ExecutionException {
...
}

ستتم متابعة الرمز للتحقّق من صحة عناوين Cloud Events:

System.out.println("Header elements");
for (String field : requiredFields) {
    if (headers.get(field) == null) {
    String msg = String.format("Missing expected header: %s.", field);
    System.out.println(msg);
    return new ResponseEntity<String>(msg, HttpStatus.BAD_REQUEST);
    } else {
    System.out.println(field + " : " + headers.get(field));
    }
}

System.out.println("Body elements");
for (String bodyField : body.keySet()) {
    System.out.println(bodyField + " : " + body.get(bodyField));
}

if (headers.get("ce-subject") == null) {
    String msg = "Missing expected header: ce-subject.";
    System.out.println(msg);
    return new ResponseEntity<String>(msg, HttpStatus.BAD_REQUEST);
} 

يمكن الآن إنشاء طلب وسيعمل الرمز على إعداد أحد هذه الطلبات لإرساله إلى Vision API:

try (ImageAnnotatorClient vision = ImageAnnotatorClient.create()) {
    List<AnnotateImageRequest> requests = new ArrayList<>();
    
    ImageSource imageSource = ImageSource.newBuilder()
        .setGcsImageUri("gs://" + bucketName + "/" + fileName)
        .build();

    Image image = Image.newBuilder()
        .setSource(imageSource)
        .build();

    Feature featureLabel = Feature.newBuilder()
        .setType(Type.LABEL_DETECTION)
        .build();
    Feature featureImageProps = Feature.newBuilder()
        .setType(Type.IMAGE_PROPERTIES)
        .build();
    Feature featureSafeSearch = Feature.newBuilder()
        .setType(Type.SAFE_SEARCH_DETECTION)
        .build();
        
    AnnotateImageRequest request = AnnotateImageRequest.newBuilder()
        .addFeatures(featureLabel)
        .addFeatures(featureImageProps)
        .addFeatures(featureSafeSearch)
        .setImage(image)
        .build();
    
    requests.add(request);

نطلب توفير 3 إمكانات رئيسية لواجهة Vision API:

• اكتشاف التصنيف: لمعرفة مضمون هذه الصور
• خصائص الصور: لإضافة سمات مثيرة للاهتمام للصورة (نحن مهتمون باللون السائد في الصورة)
• البحث الآمن: لمعرفة ما إذا كانت الصورة آمنة للعرض (يجب ألا تتضمّن محتوى للبالغين أو محتوًى طبيًا أو للبالغين أو مشاهد عنيفة)

في هذه المرحلة، يمكننا الاتصال بواجهة برمجة تطبيقات Vision:

...
logger.info("Calling the Vision API...");
BatchAnnotateImagesResponse result = vision.batchAnnotateImages(requests);
List<AnnotateImageResponse> responses = result.getResponsesList();
...

في ما يلي الردّ الذي تلقّيته من Vision API:

{
  "faceAnnotations": [],
  "landmarkAnnotations": [],
  "logoAnnotations": [],
  "labelAnnotations": [
    {
      "locations": [],
      "properties": [],
      "mid": "/m/01yrx",
      "locale": "",
      "description": "Cat",
      "score": 0.9959855675697327,
      "confidence": 0,
      "topicality": 0.9959855675697327,
      "boundingPoly": null
    },
    ✄ - - - ✄
  ],
  "textAnnotations": [],
  "localizedObjectAnnotations": [],
  "safeSearchAnnotation": {
    "adult": "VERY_UNLIKELY",
    "spoof": "UNLIKELY",
    "medical": "VERY_UNLIKELY",
    "violence": "VERY_UNLIKELY",
    "racy": "VERY_UNLIKELY",
    "adultConfidence": 0,
    "spoofConfidence": 0,
    "medicalConfidence": 0,
    "violenceConfidence": 0,
    "racyConfidence": 0,
    "nsfwConfidence": 0
  },
  "imagePropertiesAnnotation": {
    "dominantColors": {
      "colors": [
        {
          "color": {
            "red": 203,
            "green": 201,
            "blue": 201,
            "alpha": null
          },
          "score": 0.4175916016101837,
          "pixelFraction": 0.44456374645233154
        },
        ✄ - - - ✄
      ]
    }
  },
  "error": null,
  "cropHintsAnnotation": {
    "cropHints": [
      {
        "boundingPoly": {
          "vertices": [
            { "x": 0, "y": 118 },
            { "x": 1177, "y": 118 },
            { "x": 1177, "y": 783 },
            { "x": 0, "y": 783 }
          ],
          "normalizedVertices": []
        },
        "confidence": 0.41695669293403625,
        "importanceFraction": 1
      }
    ]
  },
  "fullTextAnnotation": null,
  "webDetection": null,
  "productSearchResults": null,
  "context": null
}

إذا لم يظهر أي خطأ، يمكننا المضي قدمًا، ولهذا السبب يظهر لدينا هذا إذا كان منع:

if (responses.size() == 0) {
    logger.info("No response received from Vision API.");
    return new ResponseEntity<String>(msg, HttpStatus.BAD_REQUEST);
}

AnnotateImageResponse response = responses.get(0);
if (response.hasError()) {
    logger.info("Error: " + response.getError().getMessage());
    return new ResponseEntity<String>(msg, HttpStatus.BAD_REQUEST);
}

سنحصل على تسميات الأشياء أو الفئات أو الموضوعات المعترف بها في الصورة:

List<String> labels = response.getLabelAnnotationsList().stream()
    .map(annotation -> annotation.getDescription())
    .collect(Collectors.toList());
logger.info("Annotations found:");
for (String label: labels) {
    logger.info("- " + label);
}

يسعدنا معرفة اللون السائد في الصورة:

String mainColor = "#FFFFFF";
ImageProperties imgProps = response.getImagePropertiesAnnotation();
if (imgProps.hasDominantColors()) {
    DominantColorsAnnotation colorsAnn = imgProps.getDominantColors();
    ColorInfo colorInfo = colorsAnn.getColors(0);

    mainColor = rgbHex(
        colorInfo.getColor().getRed(), 
        colorInfo.getColor().getGreen(), 
        colorInfo.getColor().getBlue());

    logger.info("Color: " + mainColor);
}

دعنا نتحقق مما إذا كانت الصورة آمنة للعرض:

boolean isSafe = false;
if (response.hasSafeSearchAnnotation()) {
    SafeSearchAnnotation safeSearch = response.getSafeSearchAnnotation();

    isSafe = Stream.of(
        safeSearch.getAdult(), safeSearch.getMedical(), safeSearch.getRacy(),
        safeSearch.getSpoof(), safeSearch.getViolence())
    .allMatch( likelihood -> 
        likelihood != Likelihood.LIKELY && likelihood != Likelihood.VERY_LIKELY
    );

    logger.info("Safe? " + isSafe);
}

نتحقّق من السمات الخاصة بالبالغين أو الانتحال أو الطب أو العنف أو المحتوى للبالغين لمعرفة ما إذا كانت هذه السمات غير مرجَّحة أو محتملة جدًا.

إذا كانت نتيجة البحث الآمن جيدة، يمكننا تخزين البيانات الوصفية في Firestore:

// Saving result to Firestore
if (isSafe) {
          ApiFuture<WriteResult> writeResult = 
               eventService.storeImage(fileName, labels,
                                       mainColor);
          logger.info("Picture metadata saved in Firestore at " + 
               writeResult.get().getUpdateTime());
}
...
  public ApiFuture<WriteResult> storeImage(String fileName, 
                                           List<String> labels, 
                                           String mainColor) {
    FirestoreOptions firestoreOptions = FirestoreOptions.getDefaultInstance();
    Firestore pictureStore = firestoreOptions.getService();

    DocumentReference doc = pictureStore.collection("pictures").document(fileName);

    Map<String, Object> data = new HashMap<>();
    data.put("labels", labels);
    data.put("color", mainColor);
    data.put("created", new Date());

    return doc.set(data, SetOptions.merge());
  }

10. إنشاء صور التطبيقات باستخدام GraalVM

في هذه الخطوة الاختيارية، عليك إنشاء JIT based app image، ثم Native Java app image باستخدام GraalVM.

لتشغيل التصميم، يجب التأكّد من أنّ لديك ملف JDK مناسب وأداة إنشاء الصور الأصلية تم تثبيتها وتهيئتها. تتوفر عدة خيارات.

To start، يُرجى تنزيل GraalVM 22.3.x Community Edition واتّباع التعليمات الواردة في صفحة تثبيت GraalVM.

يمكن تبسيط هذه العملية إلى حد كبير بمساعدة SDKMAN!

لتثبيت توزيع JDK المناسب باستخدام SDKman، ابدأ باستخدام الأمر install:

sdk install java 17.0.8-graal

توجيه SDKman إلى استخدام هذا الإصدار لكل من إصدارَي JIT وAOT:

sdk use java 17.0.8-graal

في Cloudshell، يمكنك تثبيت GraalVM وأداة النسخة الأصلية للصور باستخدام الأوامر البسيطة التالية:

# download GraalVM
wget https://download.oracle.com/graalvm/17/latest/graalvm-jdk-17_linux-x64_bin.tar.gz 
tar -xzf graalvm-jdk-17_linux-x64_bin.tar.gz

ls -lart

# configure Java 17 and GraalVM for Java 17
# note the name of the latest GraalVM version, as unpacked by the tar command
echo Existing JVM: $JAVA_HOME
cd graalvm-jdk-17.0.8+9.1

export JAVA_HOME=$PWD
cd bin
export PATH=$PWD:$PATH

echo JAVA HOME: $JAVA_HOME
echo PATH: $PATH

cd ../..

# validate the version with
java -version 

# observe
Java(TM) SE Runtime Environment Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14)
Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 17.0.8+9.1 (build 17.0.8+9-LTS-jvmci-23.0-b14, mixed mode, sharing)

أولاً، اضبط متغيّرات بيئة مشروع Google Cloud Platform:

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

يمكنك بعد ذلك الانتقال إلى الدليل الذي يحتوي على الخدمة لبدء إنشاء التمرين المعملي:

cd serverless-photosharing-workshop/services/image-analysis/java

إنشاء صورة لتطبيق JIT:

./mvnw package

لاحظ سجل الإصدار في الوحدة الطرفية:

...
[INFO] Results:
[INFO] 
[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] 
[INFO] --- maven-jar-plugin:3.3.0:jar (default-jar) @ image-analysis ---
[INFO] Building jar: /home/user/serverless-photosharing-workshop/services/image-analysis/java/target/image-analysis-0.0.1.jar
[INFO] 
[INFO] --- spring-boot-maven-plugin:3.2.0-M3:repackage (repackage) @ image-analysis ---
[INFO] Replacing main artifact /home/user/serverless-photosharing-workshop/services/image-analysis/java/target/image-analysis-0.0.1.jar with repackaged archive, adding nested dependencies in BOOT-INF/.
[INFO] The original artifact has been renamed to /home/user/serverless-photosharing-workshop/services/image-analysis/java/target/image-analysis-0.0.1.jar.original
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  15.335 s
[INFO] Finished at: 2023-10-10T19:33:25Z
[INFO] ------------------------------------------------------------------------

إنشاء صورة Native(uses AOT):

./mvnw native:compile -Pnative

راقِب سجلّ الإصدار في الوحدة الطرفية، بما في ذلك سجلّات إنشاء الصور الأصلية:

يُرجى العِلم أنّ عملية الإصدار تستغرق وقتًا أطول قليلاً حسب الجهاز الذي تختبره.

...
[2/7] Performing analysis...  [*********]                                                              (124.5s @ 4.53GB)
  29,732 (93.19%) of 31,905 classes reachable
  60,161 (70.30%) of 85,577 fields reachable
 261,973 (67.29%) of 389,319 methods reachable
   2,940 classes, 2,297 fields, and 97,421 methods registered for reflection
      81 classes,    90 fields, and    62 methods registered for JNI access
       4 native libraries: dl, pthread, rt, z
[3/7] Building universe...                                                                              (11.7s @ 4.67GB)
[4/7] Parsing methods...      [***]                                                                      (6.1s @ 5.91GB)
[5/7] Inlining methods...     [****]                                                                     (4.5s @ 4.39GB)
[6/7] Compiling methods...    [******]                                                                  (35.3s @ 4.60GB)
[7/7] Creating image...                                                                                 (12.9s @ 4.61GB)
  80.08MB (47.43%) for code area:   190,483 compilation units
  73.81MB (43.72%) for image heap:  660,125 objects and 189 resources
  14.95MB ( 8.86%) for other data
 168.84MB in total
------------------------------------------------------------------------------------------------------------------------
Top 10 packages in code area:                               Top 10 object types in image heap:
   2.66MB com.google.cloud.vision.v1p4beta1                   18.51MB byte[] for code metadata
   2.60MB com.google.cloud.vision.v1                           9.27MB java.lang.Class
   2.49MB com.google.protobuf                                  7.34MB byte[] for reflection metadata
   2.40MB com.google.cloud.vision.v1p3beta1                    6.35MB byte[] for java.lang.String
   2.17MB com.google.storage.v2                                5.72MB java.lang.String
   2.12MB com.google.firestore.v1                              4.46MB byte[] for embedded resources
   1.64MB sun.security.ssl                                     4.30MB c.oracle.svm.core.reflect.SubstrateMethodAccessor
   1.51MB i.g.xds.shaded.io.envoyproxy.envoy.config.core.v3    4.27MB byte[] for general heap data
   1.47MB com.google.cloud.vision.v1p2beta1                    2.50MB com.oracle.svm.core.hub.DynamicHubCompanion
   1.34MB i.g.x.shaded.io.envoyproxy.envoy.config.route.v3     1.17MB java.lang.Object[]
  58.34MB for 977 more packages                                9.19MB for 4667 more object types
------------------------------------------------------------------------------------------------------------------------
                        13.5s (5.7% of total time) in 75 GCs | Peak RSS: 9.44GB | CPU load: 6.13
------------------------------------------------------------------------------------------------------------------------
Produced artifacts:
 /home/user/serverless-photosharing-workshop/services/image-analysis/java/target/image-analysis (executable)
 /home/user/serverless-photosharing-workshop/services/image-analysis/java/target/image-analysis.build_artifacts.txt (txt)
========================================================================================================================
Finished generating '/home/user/serverless-photosharing-workshop/services/image-analysis/java/target/image-analysis' in 3m 57s.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  04:28 min
[INFO] Finished at: 2023-10-10T19:53:30Z
[INFO] ------------------------------------------------------------------------

11. إنشاء صور الحاويات ونشرها

لننشئ صورة حاوية في إصدارَين مختلفَين: نسخة بتنسيق JIT image والأخرى بتنسيق Native Java image.

أولاً، اضبط متغيّرات بيئة مشروع Google Cloud Platform:

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

إنشاء صورة JIT:

./mvnw spring-boot:build-image -Pji

لاحظ سجل الإصدار في الوحدة الطرفية:

[INFO]     [creator]     Timer: Saving docker.io/library/image-analysis-maven-jit:latest... started at 2023-10-10T20:00:31Z
[INFO]     [creator]     *** Images (4c84122a1826):
[INFO]     [creator]           docker.io/library/image-analysis-maven-jit:latest
[INFO]     [creator]     Timer: Saving docker.io/library/image-analysis-maven-jit:latest... ran for 6.975913605s and ended at 2023-10-10T20:00:38Z
[INFO]     [creator]     Timer: Exporter ran for 8.068588001s and ended at 2023-10-10T20:00:38Z
[INFO]     [creator]     Timer: Cache started at 2023-10-10T20:00:38Z
[INFO]     [creator]     Reusing cache layer 'paketo-buildpacks/syft:syft'
[INFO]     [creator]     Adding cache layer 'buildpacksio/lifecycle:cache.sbom'
[INFO]     [creator]     Timer: Cache ran for 200.449002ms and ended at 2023-10-10T20:00:38Z
[INFO] 
[INFO] Successfully built image 'docker.io/library/image-analysis-maven-jit:latest'
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  43.887 s
[INFO] Finished at: 2023-10-10T20:00:39Z
[INFO] ------------------------------------------------------------------------

إنشاء صورة AOT(الأصلية):.

./mvnw spring-boot:build-image -Pnative

راقِب سجلّ الإصدار في الوحدة الطرفية، بما في ذلك سجلّات إنشاء الصور الأصلية.

ملاحظة:

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

...
[INFO]     [creator]     Saving docker.io/library/image-analysis-maven-native:latest...
[INFO]     [creator]     *** Images (13167702674e):
[INFO]     [creator]           docker.io/library/image-analysis-maven-native:latest
[INFO]     [creator]     Adding cache layer 'paketo-buildpacks/bellsoft-liberica:native-image-svm'
[INFO]     [creator]     Adding cache layer 'paketo-buildpacks/syft:syft'
[INFO]     [creator]     Adding cache layer 'paketo-buildpacks/native-image:native-image'
[INFO]     [creator]     Adding cache layer 'buildpacksio/lifecycle:cache.sbom'
[INFO] 
[INFO] Successfully built image 'docker.io/library/image-analysis-maven-native:latest'
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  03:37 min
[INFO] Finished at: 2023-10-10T20:05:16Z
[INFO] ------------------------------------------------------------------------

تحقَّق من أنّه تم إنشاء الصور:

docker images | grep image-analysis

ضع علامة وادفع الصورتين إلى "آراء العملاء عبر Google":

# JIT image
docker tag image-analysis-maven-jit gcr.io/${GOOGLE_CLOUD_PROJECT}/image-analysis-maven-jit
docker push gcr.io/${GOOGLE_CLOUD_PROJECT}/image-analysis-maven-jit

# Native(AOT) image
docker tag image-analysis-maven-native gcr.io/${GOOGLE_CLOUD_PROJECT}/image-analysis-maven-native
docker push  gcr.io/${GOOGLE_CLOUD_PROJECT}/image-analysis-maven-native

12. النشر إلى التشغيل في السحابة الإلكترونية

حان وقت نشر الخدمة.

وستنشر الخدمة مرتين، إحداهما باستخدام صورة JIT والمرة الثانية باستخدام صورة AOT(الأصلية). ستعالج كلتا عمليتَي نشر الخدمتَين الصورة نفسها من الحزمة بشكل متوازٍ، وذلك لأغراض المقارنة.

أولاً، اضبط متغيّرات بيئة مشروع Google Cloud Platform:

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
gcloud config set project ${GOOGLE_CLOUD_PROJECT}
gcloud config set run/region 
gcloud config set run/platform managed
gcloud config set eventarc/location europe-west1

انشر صورة JIT ومراقبة سجلّ النشر في وحدة التحكّم:

gcloud run deploy image-analysis-jit \
     --image gcr.io/${GOOGLE_CLOUD_PROJECT}/image-analysis-maven-jit \
     --region europe-west1 \
     --memory 2Gi --allow-unauthenticated

...
Deploying container to Cloud Run service [image-analysis-jit] in project [...] region [europe-west1]
✓ Deploying... Done.                                                                                                                                                               
  ✓ Creating Revision...                                                                                                                                                           
  ✓ Routing traffic...                                                                                                                                                             
  ✓ Setting IAM Policy...                                                                                                                                                          
Done.                                                                                                                                                                              
Service [image-analysis-jit] revision [image-analysis-jvm-00009-huc] has been deployed and is serving 100 percent of traffic.
Service URL: https://image-analysis-jit-...-ew.a.run.app

انشر الصورة الأصلية وراجِع سجلّ النشر في وحدة التحكّم:

gcloud run deploy image-analysis-native \
     --image gcr.io/${GOOGLE_CLOUD_PROJECT}/image-analysis-maven-native \
     --region europe-west1 \
     --memory 2Gi --allow-unauthenticated 
...
Deploying container to Cloud Run service [image-analysis-native] in project [...] region [europe-west1]
✓ Deploying... Done.                                                                                                                                                               
  ✓ Creating Revision...                                                                                                                                                           
  ✓ Routing traffic...                                                                                                                                                             
  ✓ Setting IAM Policy...                                                                                                                                                          
Done.                                                                                                                                                                              
Service [image-analysis-native] revision [image-analysis-native-00005-ben] has been deployed and is serving 100 percent of traffic.
Service URL: https://image-analysis-native-...-ew.a.run.app

13. إعداد مشغّلات Eventarc

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

يمكنك إنشاء مشغِّل Eventarc لكي تتلقى خدمة Cloud Run إشعارات لحدث محدّد أو مجموعة أحداث. من خلال تحديد فلاتر للعامل المشغِّل، يمكنك ضبط توجيه الحدث، بما في ذلك مصدر الحدث وخدمة تشغيل السحابة الإلكترونية المستهدَفة.

أولاً، اضبط متغيّرات بيئة مشروع Google Cloud Platform:

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
gcloud config set project ${GOOGLE_CLOUD_PROJECT}
gcloud config set run/region 
gcloud config set run/platform managed
gcloud config set eventarc/location europe-west1

منح pubsub.publisher لحساب خدمة Cloud Storage:

SERVICE_ACCOUNT="$(gsutil kms serviceaccount -p ${GOOGLE_CLOUD_PROJECT})"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
    --member="serviceAccount:${SERVICE_ACCOUNT}" \
    --role='roles/pubsub.publisher'

عليك إعداد مشغِّلات Eventarc لكل من صور JIT وصور الخدمة الأصلية لمعالجة الصورة:

gcloud eventarc triggers list --location=eu

gcloud eventarc triggers create image-analysis-jit-trigger \
     --destination-run-service=image-analysis-jit \
     --destination-run-region=europe-west1 \
     --location=eu \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=uploaded-pictures-${GOOGLE_CLOUD_PROJECT}" \
     --service-account=${PROJECT_NUMBER}[e-mail]

gcloud eventarc triggers create image-analysis-native-trigger \
     --destination-run-service=image-analysis-native \
     --destination-run-region=europe-west1 \
     --location=eu \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=uploaded-pictures-${GOOGLE_CLOUD_PROJECT}" \
     --service-account=${PROJECT_NUMBER}[e-mail]    

لاحظ أنه قد تم إنشاء المشغلين:

gcloud eventarc triggers list --location=eu

14. إصدارات الخدمة التجريبية

بعد اكتمال عمليات نشر الخدمة بنجاح، ستنشر صورة على Cloud Storage، لتتعرّف على ما إذا تم استدعاء خدماتنا وما إذا كانت Vision API سترجعه وما إذا كانت البيانات الوصفية محفوظة في Firestore.

انتقِل مرة أخرى إلى Cloud Storage وانقر على الحزمة التي أنشأناها في بداية التمرين المعملي:

بعد الانتقال إلى صفحة تفاصيل الحزمة، انقر على الزر Upload files لتحميل صورة.

على سبيل المثال، يتم توفير صورة GeekHour.jpeg مع قاعدة الرموز لديك ضمن /services/image-analysis/java. اختَر صورة واضغط على الزر Open button:

يمكنك الآن التحقّق من تنفيذ الخدمة، بدءًا من image-analysis-jit، يليها image-analysis-native.

من "الهامبرغر" (⇧)، وانتقِل إلى خدمة "Cloud Run > image-analysis-jit".

انقر فوق السجلات وراقب الإخراج:

وفي قائمة السجلّات، يظهر لي أنّه تم استدعاء image-analysis-jit لخدمة JIT.

تشير السجلات إلى بدء تنفيذ الخدمة ونهايتها. وفي المنتصف، يمكننا رؤية السجلات التي وضعناها في دالتنا مع عبارات السجل على مستوى "معلومات". يتضح لنا ما يلي:

• تفاصيل الحدث الذي يؤدي إلى تشغيل الدالة،
• النتائج الأولية من طلب بيانات من واجهة Vision API
• الملصقات التي تم العثور عليها في الصورة التي قمنا بتحميلها،
• معلومات الألوان السائدة،
• ما إذا كانت الصورة آمنة للعرض
• وفي النهاية، تم تخزين تلك البيانات الوصفية حول الصورة في Firestore.

ستكرّر العملية لخدمة image-analysis-native.

من "الهامبرغر" (⇧)، وانتقِل إلى خدمة "Cloud Run > image-analysis-native".

انقر فوق السجلات وراقب الإخراج:

ننصحك الآن بمعرفة ما إذا كان قد تم تخزين البيانات الوصفية للصورة في Fiorestore.

مرة أخرى من "الهامبرغر" (⇧)، وانتقِل إلى قسم "Firestore". في القسم الفرعي Data (المعروض تلقائيًا)، من المفترض أن تظهر لك مجموعة pictures مع إضافة مستند جديد مطابق للصورة التي حمّلتها للتو:

15. إخلاء مساحة تخزين (اختياري)

ملاحظة: إذا كنت تنوي مواصلة استخدام ميزات اختبارية أخرى في السلسلة، يمكنك تخطّي هذه الخطوة.

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

حذف الحزمة:

gsutil rb gs://${BUCKET_PICTURES}

حذف الدالة:

gcloud functions delete picture-uploaded --region europe-west1 -q

احذف مجموعة Firestore من خلال تحديد "حذف المجموعة" من المجموعة:

بدلاً من ذلك، يمكنك حذف المشروع بالكامل:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT} 

16. تهانينا!

تهانينا! لقد قمت بتنفيذ أول خدمة إدارة مفاتيح تشفير بنجاح للمشروع!

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

• تخزين في السحابة الإلكترونية
• Cloud Run
• واجهة برمجة تطبيقات Cloud Vision
• Cloud Firestore
• صور Java أصلية

الخطوات التالية

• صور يومية: التمرين المعملي 2: إنشاء صور مصغرة للصور الكبيرة