التعرّف على النص في "الصور" بأمان من خلال Cloud Vision باستخدام مصادقة Firebase والوظائف على Android

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

إحدى الطرق لإنشاء واجهة برمجة تطبيقات REST هذه هي باستخدام مصادقة ووظائف Firebase، التي تمنحك مدخلاً مُدارًا بدون خادم إلى واجهات Google Cloud APIs التي تعالج المصادقة ويمكن طلبها من تطبيقك للأجهزة الجوّالة باستخدام SDK المنشأة مسبقًا.

يوضِّح هذا الدليل كيفية استخدام هذا الأسلوب لطلب بيانات Cloud Vision API من تطبيقك. ستسمح هذه الطريقة لجميع المستخدمين الذين تمت مصادقتهم بالوصول إلى الخدمات التي تتم فوترتها عبر Cloud Vision من خلال مشروعك على Google Cloud، وبالتالي قبل المتابعة، تحقَّق مما إذا كانت آلية المصادقة هذه كافية لحالة الاستخدام لديك.

قبل البدء

ضبط مشروعك

  1. إذا لم تكن قد فعلت ذلك بالفعل، إضافة Firebase إلى مشروع Android

  2. إذا لم يسبق لك تفعيل واجهات برمجة التطبيقات المستنِدة إلى السحابة الإلكترونية لمشروعك، يُرجى إجراء ذلك الآن:

    1. افتح Firebase ML. صفحة واجهات برمجة التطبيقات لوحدة تحكُّم Firebase.

    2. إذا لم تكن قد أجريت ترقية لمشروعك إلى خطة أسعار Blaze، انقر على يجب الترقية لإجراء ذلك. (ستتم مطالبتك بالترقية فقط إذا كان مشروعك ليس على خطة Blaze).

      يمكن للمشروعات على مستوى Blaze فقط استخدام واجهات برمجة التطبيقات المستنِدة إلى السحابة الإلكترونية.

    3. إذا لم تكن واجهات برمجة التطبيقات المستنِدة إلى السحابة الإلكترونية مُفعَّلة، انقر على تفعيل البيانات المستندة إلى السحابة الإلكترونية. API.
  3. ضبط مفاتيح واجهة برمجة التطبيقات الحالية في Firebase لمنع الوصول إلى السحابة الإلكترونية واجهة Vision API:
    1. افتح صفحة بيانات الاعتماد في Cloud Console.
    2. لكل مفتاح واجهة برمجة تطبيقات في القائمة، افتح عرض التعديل، وفي قسم "المفتاح" قسم "القيود"، أضِف جميع واجهات برمجة التطبيقات المتاحة باستثناء Cloud Vision. واجهة برمجة التطبيقات إلى القائمة.

نشر الدالة القابلة للاستدعاء

بعد ذلك، انشر وظيفة السحابة الإلكترونية التي ستستخدمها للربط بين تطبيقك والسحابة الإلكترونية Vision API يحتوي مستودع functions-samples على مثال التي يمكنك استخدامها.

سيتيح الوصول إلى Cloud Vision API من خلال هذه الوظيفة تلقائيًا وصول المستخدمين الذين تمت مصادقتهم على تطبيقك إلى Cloud Vision API فقط يمكنك الدالة وفقًا للمتطلبات المختلفة.

لنشر الدالة:

  1. استنساخ مستودع نماذج الدوال أو نزِّله. والتغيير إلى الدليل Node-1st-gen/vision-annotate-image: 
    git clone https://github.com/firebase/functions-samples
cd Node-1st-gen/vision-annotate-image
  2. ثبِّت التبعيّات: 
    cd functions
npm install
cd ..
  3. إذا لم يكن لديك واجهة سطر الأوامر في Firebase، عليك تثبيته.
  4. إعداد مشروع Firebase في vision-annotate-image الدليل. اختَر مشروعك من القائمة عندما يُطلب منك ذلك. 
    firebase init
  5. نشر الدالة: 
    firebase deploy --only functions:annotateImage

إضافة مصادقة Firebase إلى تطبيقك

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

أضف التبعيات اللازمة إلى تطبيقك

  • إضافة الاعتمادية لمكتبات Cloud Functions في Firebase (العميل) وgson Android إلى ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle): 
    implementation("com.google.firebase:firebase-functions:21.0.0")
implementation("com.google.code.gson:gson:2.8.6")

    • أنت الآن جاهز لبدء التعرف على النص في الصور.

    1- تحضير صورة الإدخال

    لاستدعاء Cloud Vision، يجب تنسيق الصورة كسلسلة بترميز base64. لمعالجة صورة من معرف موارد منتظم (URI) لملف محفوظ:
    1. الحصول على الصورة ككائن Bitmap:

      Kotlin+KTX

      var bitmap: Bitmap = MediaStore.Images.Media.getBitmap(contentResolver, uri)

      Java

      Bitmap bitmap = MediaStore.Images.Media.getBitmap(getContentResolver(), uri);
    2. يمكنك أيضًا تصغير حجم الصورة لتوفير النطاق الترددي. يمكنك الاطّلاع على أحجام الصور المقترَحة في Cloud Vision

      Kotlin+KTX

      private fun scaleBitmapDown(bitmap: Bitmap, maxDimension: Int): Bitmap {
    val originalWidth = bitmap.width
    val originalHeight = bitmap.height
    var resizedWidth = maxDimension
    var resizedHeight = maxDimension
    if (originalHeight > originalWidth) {
        resizedHeight = maxDimension
        resizedWidth =
            (resizedHeight * originalWidth.toFloat() / originalHeight.toFloat()).toInt()
    } else if (originalWidth > originalHeight) {
        resizedWidth = maxDimension
        resizedHeight =
            (resizedWidth * originalHeight.toFloat() / originalWidth.toFloat()).toInt()
    } else if (originalHeight == originalWidth) {
        resizedHeight = maxDimension
        resizedWidth = maxDimension
    }
    return Bitmap.createScaledBitmap(bitmap, resizedWidth, resizedHeight, false)
}

      Java

      private Bitmap scaleBitmapDown(Bitmap bitmap, int maxDimension) {
    int originalWidth = bitmap.getWidth();
    int originalHeight = bitmap.getHeight();
    int resizedWidth = maxDimension;
    int resizedHeight = maxDimension;

    if (originalHeight > originalWidth) {
        resizedHeight = maxDimension;
        resizedWidth = (int) (resizedHeight * (float) originalWidth / (float) originalHeight);
    } else if (originalWidth > originalHeight) {
        resizedWidth = maxDimension;
        resizedHeight = (int) (resizedWidth * (float) originalHeight / (float) originalWidth);
    } else if (originalHeight == originalWidth) {
        resizedHeight = maxDimension;
        resizedWidth = maxDimension;
    }
    return Bitmap.createScaledBitmap(bitmap, resizedWidth, resizedHeight, false);
}

      Kotlin+KTX

      // Scale down bitmap size
bitmap = scaleBitmapDown(bitmap, 640)

      Java

      // Scale down bitmap size
bitmap = scaleBitmapDown(bitmap, 640);
    3. تحويل كائن الصورة النقطية إلى سلسلة بترميز base64:

      Kotlin+KTX

      // Convert bitmap to base64 encoded string
val byteArrayOutputStream = ByteArrayOutputStream()
bitmap.compress(Bitmap.CompressFormat.JPEG, 100, byteArrayOutputStream)
val imageBytes: ByteArray = byteArrayOutputStream.toByteArray()
val base64encoded = Base64.encodeToString(imageBytes, Base64.NO_WRAP)

      Java

      // Convert bitmap to base64 encoded string
ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
bitmap.compress(Bitmap.CompressFormat.JPEG, 100, byteArrayOutputStream);
byte[] imageBytes = byteArrayOutputStream.toByteArray();
String base64encoded = Base64.encodeToString(imageBytes, Base64.NO_WRAP);
      4. يجب أن تكون الصورة التي يمثّلها الكائن Bitmap مستقيمًا، دون الحاجة إلى دوران إضافي.

    2- استدعاء الدالة القابلة للاستدعاء للتعرّف على النص

    للتعرف على نص في صورة، يمكنك استدعاء الدالة القابلة للاستدعاء، وتمرير طلب JSON Cloud Vision

    1. أولاً، عليك إعداد مثيل من دوال السحابة:

      Kotlin+KTX 

      private lateinit var functions: FirebaseFunctions
// ...
functions = Firebase.functions

      Java 

      private FirebaseFunctions mFunctions;
// ...
mFunctions = FirebaseFunctions.getInstance();

    2. حدد طريقة لاستدعاء الدالة:

      Kotlin+KTX 

      private fun annotateImage(requestJson: String): Task<JsonElement> {
    return functions
        .getHttpsCallable("annotateImage")
        .call(requestJson)
        .continueWith { task ->
            // This continuation runs on either success or failure, but if the task
            // has failed then result will throw an Exception which will be
            // propagated down.
            val result = task.result?.data
            JsonParser.parseString(Gson().toJson(result))
        }
}

      Java 

      private Task<JsonElement> annotateImage(String requestJson) {
    return mFunctions
            .getHttpsCallable("annotateImage")
            .call(requestJson)
            .continueWith(new Continuation<HttpsCallableResult, JsonElement>() {
                @Override
                public JsonElement then(@NonNull Task<HttpsCallableResult> task) {
                    // This continuation runs on either success or failure, but if the task
                    // has failed then getResult() will throw an Exception which will be
                    // propagated down.
                    return JsonParser.parseString(new Gson().toJson(task.getResult().getData()));
                }
            });
}

    3. أنشِئ طلب JSON. تدعم Cloud Vision API نوعَين. ميزة رصد النص: TEXT_DETECTION وDOCUMENT_TEXT_DETECTION. الاطّلاع على مستندات OCR في Cloud Vision لمعرفة الفرق بين حالتي الاستخدام.

      Kotlin+KTX 

      // Create json request to cloud vision
val request = JsonObject()
// Add image to request
val image = JsonObject()
image.add("content", JsonPrimitive(base64encoded))
request.add("image", image)
// Add features to the request
val feature = JsonObject()
feature.add("type", JsonPrimitive("TEXT_DETECTION"))
// Alternatively, for DOCUMENT_TEXT_DETECTION:
// feature.add("type", JsonPrimitive("DOCUMENT_TEXT_DETECTION"))
val features = JsonArray()
features.add(feature)
request.add("features", features)

      Java 

      // Create json request to cloud vision
JsonObject request = new JsonObject();
// Add image to request
JsonObject image = new JsonObject();
image.add("content", new JsonPrimitive(base64encoded));
request.add("image", image);
//Add features to the request
JsonObject feature = new JsonObject();
feature.add("type", new JsonPrimitive("TEXT_DETECTION"));
// Alternatively, for DOCUMENT_TEXT_DETECTION:
//feature.add("type", new JsonPrimitive("DOCUMENT_TEXT_DETECTION"));
JsonArray features = new JsonArray();
features.add(feature);
request.add("features", features);

      يمكنك تقديم تلميحات للّغة (إجراء اختياري) للمساعدة في التعرّف على اللغة (يمكنك الاطّلاع على اللغات المعتمَدة):

      Kotlin+KTX 

      val imageContext = JsonObject()
val languageHints = JsonArray()
languageHints.add("en")
imageContext.add("languageHints", languageHints)
request.add("imageContext", imageContext)

      Java 

      JsonObject imageContext = new JsonObject();
JsonArray languageHints = new JsonArray();
languageHints.add("en");
imageContext.add("languageHints", languageHints);
request.add("imageContext", imageContext);

    4. أخيرًا، استدعِ الدالة:

      Kotlin+KTX 

      annotateImage(request.toString())
    .addOnCompleteListener { task ->
        if (!task.isSuccessful) {
            // Task failed with an exception
            // ...
        } else {
            // Task completed successfully
            // ...
        }
    }

      Java 

      annotateImage(request.toString())
        .addOnCompleteListener(new OnCompleteListener<JsonElement>() {
            @Override
            public void onComplete(@NonNull Task<JsonElement> task) {
                if (!task.isSuccessful()) {
                    // Task failed with an exception
                    // ...
                } else {
                    // Task completed successfully
                    // ...
                }
            }
        });

    3- استخراج النص من مجموعات النصوص التي تم التعرّف عليها

    إذا نجحت عملية التعرّف على النص، ستُطرح استجابة JSON BatchAnnotateImagesResponse في نتيجة المهمة. يمكن العثور على التعليقات التوضيحية النصية في fullTextAnnotation.

    يمكنك الحصول على النص الذي تم التعرّف عليه كسلسلة في الحقل text. على سبيل المثال:

    Kotlin+KTX 

    val annotation = task.result!!.asJsonArray[0].asJsonObject["fullTextAnnotation"].asJsonObject
System.out.format("%nComplete annotation:")
System.out.format("%n%s", annotation["text"].asString)

    Java 

    JsonObject annotation = task.getResult().getAsJsonArray().get(0).getAsJsonObject().get("fullTextAnnotation").getAsJsonObject();
System.out.format("%nComplete annotation:%n");
System.out.format("%s%n", annotation.get("text").getAsString());

    ويمكنك أيضًا الحصول على معلومات خاصة بمناطق الصورة. لكل block، paragraph وword وsymbol، يمكنك التعرّف على النص في المنطقة. وإحداثيات المنطقة المحيطة. على سبيل المثال:

    Kotlin+KTX 

    for (page in annotation["pages"].asJsonArray) {
    var pageText = ""
    for (block in page.asJsonObject["blocks"].asJsonArray) {
        var blockText = ""
        for (para in block.asJsonObject["paragraphs"].asJsonArray) {
            var paraText = ""
            for (word in para.asJsonObject["words"].asJsonArray) {
                var wordText = ""
                for (symbol in word.asJsonObject["symbols"].asJsonArray) {
                    wordText += symbol.asJsonObject["text"].asString
                    System.out.format(
                        "Symbol text: %s (confidence: %f)%n",
                        symbol.asJsonObject["text"].asString,
                        symbol.asJsonObject["confidence"].asFloat,
                    )
                }
                System.out.format(
                    "Word text: %s (confidence: %f)%n%n",
                    wordText,
                    word.asJsonObject["confidence"].asFloat,
                )
                System.out.format("Word bounding box: %s%n", word.asJsonObject["boundingBox"])
                paraText = String.format("%s%s ", paraText, wordText)
            }
            System.out.format("%nParagraph: %n%s%n", paraText)
            System.out.format("Paragraph bounding box: %s%n", para.asJsonObject["boundingBox"])
            System.out.format("Paragraph Confidence: %f%n", para.asJsonObject["confidence"].asFloat)
            blockText += paraText
        }
        pageText += blockText
    }
}

    Java 

    for (JsonElement page : annotation.get("pages").getAsJsonArray()) {
    StringBuilder pageText = new StringBuilder();
    for (JsonElement block : page.getAsJsonObject().get("blocks").getAsJsonArray()) {
        StringBuilder blockText = new StringBuilder();
        for (JsonElement para : block.getAsJsonObject().get("paragraphs").getAsJsonArray()) {
            StringBuilder paraText = new StringBuilder();
            for (JsonElement word : para.getAsJsonObject().get("words").getAsJsonArray()) {
                StringBuilder wordText = new StringBuilder();
                for (JsonElement symbol : word.getAsJsonObject().get("symbols").getAsJsonArray()) {
                    wordText.append(symbol.getAsJsonObject().get("text").getAsString());
                    System.out.format("Symbol text: %s (confidence: %f)%n", symbol.getAsJsonObject().get("text").getAsString(), symbol.getAsJsonObject().get("confidence").getAsFloat());
                }
                System.out.format("Word text: %s (confidence: %f)%n%n", wordText.toString(), word.getAsJsonObject().get("confidence").getAsFloat());
                System.out.format("Word bounding box: %s%n", word.getAsJsonObject().get("boundingBox"));
                paraText.append(wordText.toString()).append(" ");
            }
            System.out.format("%nParagraph:%n%s%n", paraText);
            System.out.format("Paragraph bounding box: %s%n", para.getAsJsonObject().get("boundingBox"));
            System.out.format("Paragraph Confidence: %f%n", para.getAsJsonObject().get("confidence").getAsFloat());
            blockText.append(paraText);
        }
        pageText.append(blockText);
    }
}