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

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

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

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

قبل البدء

ضبط مشروعك

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

استخدِم Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.

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

بعد ذلك، نفِّذ بعض خطوات الإعداد داخل التطبيق:

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

    Swift

    import FirebaseMLModelDownloader

    Objective-C

    @import FirebaseMLModelDownloader;

تتبقى بعض خطوات الإعداد الإضافية، وسنكون جاهزين للانطلاق:

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

    1. افتح صفحة Firebase ML APIs في Firebase console.

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

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

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

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

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

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

لنشر الدالة، اتّبِع الخطوات التالية:

  1. استنسِخ مستودع functions-samples أو نزِّله، وانتقِل إلى الدليل 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 CLI، ثبِّته.
  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. أولاً، ابدأ مثيلاً من Cloud Functions:

    Swift

    lazy var functions = Functions.functions()

    Objective-C

    @property(strong, nonatomic) FIRFunctions *functions;

  2. أنشِئ طلبًا مع ضبط النوع على LANDMARK_DETECTION:

    Swift

    let requestData = [
  "image": ["content": base64encodedImage],
  "features": ["maxResults": 5, "type": "LANDMARK_DETECTION"]
]

    Objective-C

    NSDictionary *requestData = @{
  @"image": @{@"content": base64encodedImage},
  @"features": @{@"maxResults": @5, @"type": @"LANDMARK_DETECTION"}
};

  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 في نتيجة المهمة. يمثّل كل عنصر في مصفوفة landmarkAnnotations معلمًا تم التعرّف عليه في الصورة. لكل معلم، يمكنك الحصول على إحداثيات المربّع المحيط به في الصورة المُدخَلة واسم المعلم وخط العرض وخط الطول ورقم تعريف كيان الرسم البياني المعرفي (إن توفّر) وعلامة الثقة للمطابقة. على سبيل المثال:

Swift

if let labelArray = (result?.data as? [String: Any])?["landmarkAnnotations"] as? [[String:Any]] {
  for labelObj in labelArray {
    let landmarkName = labelObj["description"]
    let entityId = labelObj["mid"]
    let score = labelObj["score"]
    let bounds = labelObj["boundingPoly"]
    // Multiple locations are possible, e.g., the location of the depicted
    // landmark and the location the picture was taken.
    guard let locations = labelObj["locations"] as? [[String: [String: Any]]] else { continue }
    for location in locations {
      let latitude = location["latLng"]?["latitude"]
      let longitude = location["latLng"]?["longitude"]
    }
  }
}

Objective-C

NSArray *labelArray = result.data[@"landmarkAnnotations"];
for (NSDictionary *labelObj in labelArray) {
  NSString *landmarkName = labelObj[@"description"];
  NSString *entityId = labelObj[@"mid"];
  NSNumber *score = labelObj[@"score"];
  NSArray *bounds = labelObj[@"boundingPoly"];
  // Multiple locations are possible, e.g., the location of the depicted
  // landmark and the location the picture was taken.
  NSArray *locations = labelObj[@"locations"];
  for (NSDictionary *location in locations) {
    NSNumber *latitude = location[@"latLng"][@"latitude"];
    NSNumber *longitude = location[@"latLng"][@"longitude"];
  }
}