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

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

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

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

قبل البدء

ضبط مشروعك

إذا لم يسبق لك إضافة Firebase إلى تطبيقك، عليك اتّباع الخطوات الواردة في دليل البدء.

يمكنك استخدام "مدير حزم Swift" لتثبيت اعتماديات Firebase وإدارتها.

  1. في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى File > Add Packages (ملف > إضافة حِزم).
  2. أضِف مستودع حزمة تطوير البرامج (SDK) لمنصّات Firebase Apple عندما يُطلب منك ذلك:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. اختَر مكتبة تعلُّم الآلة في Firebase.
  4. أضِف العلامة -ObjC إلى القسم علامات الروابط الأخرى في إعدادات إصدار هدفك.
  5. عند الانتهاء، ستبدأ خدمة Xcode تلقائيًا في حلّ المشاكل المتعلّقة بالعناصر التي تعتمد عليها وتنزيلها في الخلفية.

بعد ذلك، يمكنك إجراء بعض الإعدادات داخل التطبيق:

  1. في تطبيقك، استورِد Firebase:

    Swift

    import FirebaseMLModelDownloader

    Objective-C

    @import FirebaseMLModelDownloader;

في ما يلي بعض خطوات الضبط الإضافية، ونحن جاهزون لبدء الاستخدام:

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

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

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

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

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

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

بعد ذلك، انشر وظيفة Cloud التي ستستخدمها للربط بين تطبيقك وCloud 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 إلى تطبيقك.

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

استخدِم Swift Package Manager لتثبيت "وظائف السحابة الإلكترونية لمكتبة Firebase".

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

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

لطلب البيانات من Cloud Vision، يجب تنسيق الصورة كسلسلة بترميز base64. لمعالجة UIImage:

Swift

guard let imageData = uiImage.jpegData(compressionQuality: 1.0) else { return }
let base64encodedImage = imageData.base64EncodedString()

Objective-C

NSData *imageData = UIImageJPEGRepresentation(uiImage, 1.0f);
NSString *base64encodedImage =
  [imageData base64EncodedStringWithOptions:NSDataBase64Encoding76CharacterLineLength];

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

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

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

    Swift

    lazy var functions = Functions.functions()

    Objective-C

    @property(strong, nonatomic) FIRFunctions *functions;

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

    Swift

    let requestData = [
  "image": ["content": base64encodedImage],
  "features": ["type": "TEXT_DETECTION"],
  "imageContext": ["languageHints": ["en"]]
]

    Objective-C

    NSDictionary *requestData = @{
  @"image": @{@"content": base64encodedImage},
  @"features": @{@"type": @"TEXT_DETECTION"},
  @"imageContext": @{@"languageHints": @[@"en"]}
};

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

    Swift

    do {
  let result = try await functions.httpsCallable("annotateImage").call(requestData)
  print(result)
} catch {
  if let error = error as NSError? {
    if error.domain == FunctionsErrorDomain {
      let code = FunctionsErrorCode(rawValue: error.code)
      let message = error.localizedDescription
      let details = error.userInfo[FunctionsErrorDetailsKey]
    }
    // ...
  }
}

    Objective-C

    [[_functions HTTPSCallableWithName:@"annotateImage"]
                          callWithObject:requestData
                              completion:^(FIRHTTPSCallableResult * _Nullable result, NSError * _Nullable error) {
        if (error) {
          if ([error.domain isEqualToString:@"com.firebase.functions"]) {
            FIRFunctionsErrorCode code = error.code;
            NSString *message = error.localizedDescription;
            NSObject *details = error.userInfo[@"details"];
          }
          // ...
        }
        // Function completed succesfully
        // Get information about labeled objects

      }];

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

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

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

Swift

let annotation = result.flatMap { $0.data as? [String: Any] }
    .flatMap { $0["fullTextAnnotation"] }
    .flatMap { $0 as? [String: Any] }
guard let annotation = annotation else { return }

if let text = annotation["text"] as? String {
  print("Complete annotation: \(text)")
}

Objective-C

NSDictionary *annotation = result.data[@"fullTextAnnotation"];
if (!annotation) { return; }
NSLog(@"\nComplete annotation:");
NSLog(@"\n%@", annotation[@"text"]);

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

Swift

guard let pages = annotation["pages"] as? [[String: Any]] else { return }
for page in pages {
  var pageText = ""
  guard let blocks = page["blocks"] as? [[String: Any]] else { continue }
  for block in blocks {
    var blockText = ""
    guard let paragraphs = block["paragraphs"] as? [[String: Any]] else { continue }
    for paragraph in paragraphs {
      var paragraphText = ""
      guard let words = paragraph["words"] as? [[String: Any]] else { continue }
      for word in words {
        var wordText = ""
        guard let symbols = word["symbols"] as? [[String: Any]] else { continue }
        for symbol in symbols {
          let text = symbol["text"] as? String ?? ""
          let confidence = symbol["confidence"] as? Float ?? 0.0
          wordText += text
          print("Symbol text: \(text) (confidence: \(confidence)%n")
        }
        let confidence = word["confidence"] as? Float ?? 0.0
        print("Word text: \(wordText) (confidence: \(confidence)%n%n")
        let boundingBox = word["boundingBox"] as? [Float] ?? [0.0, 0.0, 0.0, 0.0]
        print("Word bounding box: \(boundingBox.description)%n")
        paragraphText += wordText
      }
      print("%nParagraph: %n\(paragraphText)%n")
      let boundingBox = paragraph["boundingBox"] as? [Float] ?? [0.0, 0.0, 0.0, 0.0]
      print("Paragraph bounding box: \(boundingBox)%n")
      let confidence = paragraph["confidence"] as? Float ?? 0.0
      print("Paragraph Confidence: \(confidence)%n")
      blockText += paragraphText
    }
    pageText += blockText
  }
}

Objective-C

for (NSDictionary *page in annotation[@"pages"]) {
  NSMutableString *pageText = [NSMutableString new];
  for (NSDictionary *block in page[@"blocks"]) {
    NSMutableString *blockText = [NSMutableString new];
    for (NSDictionary *paragraph in block[@"paragraphs"]) {
      NSMutableString *paragraphText = [NSMutableString new];
      for (NSDictionary *word in paragraph[@"words"]) {
        NSMutableString *wordText = [NSMutableString new];
        for (NSDictionary *symbol in word[@"symbols"]) {
          NSString *text = symbol[@"text"];
          [wordText appendString:text];
          NSLog(@"Symbol text: %@ (confidence: %@\n", text, symbol[@"confidence"]);
        }
        NSLog(@"Word text: %@ (confidence: %@\n\n", wordText, word[@"confidence"]);
        NSLog(@"Word bounding box: %@\n", word[@"boundingBox"]);
        [paragraphText appendString:wordText];
      }
      NSLog(@"\nParagraph: \n%@\n", paragraphText);
      NSLog(@"Paragraph bounding box: %@\n", paragraph[@"boundingBox"]);
      NSLog(@"Paragraph Confidence: %@\n", paragraph[@"confidence"]);
      [blockText appendString:paragraphText];
    }
    [pageText appendString:blockText];
  }
}