التحقّق من حالة تسجيل التطبيق باستخدام واجهة برمجة التطبيقات Android Developer ID Status API

يمكنك استخدام Android Developer Status API للتحقّق مما إذا كان اسم حزمة تطبيق Android مسجّلاً لدى مطوّر معتمَد. إذا كنت تنشئ أدوات تطوير برامج أو بيئات تطوير متكاملة (IDE) أو مهام سير عمل تلقائية للتكامل المستمر/النشر المستمر (CI/CD)، يمكنك دمج واجهة برمجة التطبيقات من خادم إلى خادم هذه لإجراء ما يلي:

• التحقّق مما إذا كان اسم حزمة تطبيق مسجّلاً لدى مطوّر معتمَد
• التحقّق مما إذا كان الملف المرجعي لشهادة توقيع تطبيق SHA-256 يطابق بيانات الاعتماد المحفوظة لاسم الحزمة المسجَّل
• مطالبة المطوّرين بتسجيل التطبيقات غير المعروفة في برنامج التحقّق من هوية مطوّر Android من خلال واجهة الأداة

تم تصميم واجهة برمجة التطبيقات هذه لدعم مهام سير عمل المطوّرين المختلفة:

يوضّح هذا الدليل كيفية إكمال المهام التالية:

1. إعداد إذن الوصول إلى Google Cloud API والمصادقة
2. التحقّق مما إذا كان مطوّر معتمَد قد سجّل اسم حزمة تطبيق مع ملف مرجعي لشهادة عامة SHA-256 في برنامج التحقّق من هوية مطوّر Android، باستخدام الملف المرجعي لشهادة SHA-256 العامة المقدَّمة أو ملف مرجعي مختلف لشهادة SHA-256 العامة
3. التعامل مع حالات تسجيل واجهة برمجة التطبيقات في بيئة التطوير المتكاملة أو مهام سير عمل أداة المطوّر

المتطلبات الأساسية

هذا المستند مخصّص لمطوّري تطبيقات Android أو مطوّري أدوات تطوير البرامج. قبل البدء، يجب أن يتوفّر لديك ما يلي:

• إذن وصول إداري إلى مشروع على السحابة الإلكترونية من Google Cloud
• فهم أساسي لواجهات برمجة تطبيقات RESTful وتنسيق JSON والملفات المرجعية لشهادات SHA-256

يجب أيضًا أن تكون على دراية بالمصطلحات التالية:

نقطة نهاية الخدمة

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

https://androiddeveloperidstatus.googleapis.com

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

لاستخدام Android Developer ID Status API، عليك إكمال خطوات الإعداد لإنشاء مشروع وتفعيل واجهة برمجة التطبيقات.

إنشاء مشروع Google Cloud

1. أنشئ حسابًا على Google Cloud إذا لم يكن لديك حساب.
2. افتح Google Cloud Console.
3. أنشئ مشروعًا على Google Cloud.

تفعيل واجهة برمجة التطبيقات في مشروعك

1. في Google Cloud Console، انتقِل إلى واجهات برمجة التطبيقات والخدمات > المكتبة.
2. اختَر مشروعك من القائمة المنسدلة.
3. ابحث عن Android Developer ID Status API.
4. انقر على تفعيل.

المصادقة

تتيح واجهة برمجة التطبيقات استخدام بيانات اعتماد مفتاح واجهة برمجة التطبيقات. للحصول على مفتاح واجهة برمجة التطبيقات:

1. في Google Cloud Console، انتقِل إلى واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
2. انقر على + إنشاء بيانات اعتماد واختَر مفتاح واجهة برمجة التطبيقات.
3. اضبط المفتاح وانسخه. استخدِم هذا المفتاح في رؤوس الطلبات.

التحقّق من حالة تسجيل التطبيق

يمكنك طلب البحث عن المورد PackageRegistrationStatus للتحقّق من اسم حزمة وحده أو التحقّق من اسم حزمة مقترن بملف مرجعي لشهادة معيّنة.

التحقّق من اسم حزمة

للتحقّق مما إذا كان أي مطوّر معتمَد قد سجّل اسم حزمة تطبيق، أرسِل طلب GET مصادَقًا يحتوي على اسم حزمة تطبيق Android (على سبيل المثال، com.example.app) إلى نقطة النهاية packageRegistrationStatus:check بدون مَعلمات اختيارية:

الطلب:

curl -X GET "https://androiddeveloperidstatus.googleapis.com/v1/packages/com.example.app/packageRegistrationStatus:check" \
  -H "X-Goog-Api-Key: [key]"

النتائج

الردّ (تم التسجيل):

إذا كان اسم الحزمة مسجّلاً، ستتلقّى نص استجابة HTTP التالي مع رمز استجابة HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED"
}

الإجراء المقترَح: إذا كنت تجري هذا التحقّق نيابةً عن مطوّر آخر، أبلِغه بأنّ اسم الحزمة مسجَّل.

الردّ (لم يتم التسجيل):

إذا لم يكن اسم الحزمة مسجّلاً، ستتلقّى نص استجابة HTTP التالي مع رمز استجابة HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "NOT_REGISTERED"
}

الإجراء المقترَح: إذا كنت تجري هذا التحقّق نيابةً عن مطوّر آخر، أبلِغه بأنّ اسم الحزمة غير مسجَّل.

مثال بلغة Java

يستدعي مثال Java هذا واجهة برمجة التطبيقات بدون أي مَعلمات طلب بحث للتحقّق مما إذا كان اسم الحزمة مسجّلاً.

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CheckPackageNameClient {

  private static final String API_ENDPOINT = "https://androiddeveloperidstatus.googleapis.com";

  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY";
    String packageName = "com.example.app";

    try {
      String response = checkPackageRegistrationStatus(apiKey, packageName);
      System.out.println("Response: " + response);
    } catch (IOException | InterruptedException e) {
      e.printStackTrace();
    }
  }

  /**
   *   Checks the registration status of an Android package.
   */
  public static String checkPackageRegistrationStatus(String apiKey, String packageName)
      throws IOException, InterruptedException {

    String fullUrl = String.format("%s/v1/packages/%s/packageRegistrationStatus:check", API_ENDPOINT, packageName);

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(fullUrl))
        .header("Accept", "application/json")
        .header("X-Goog-Api-Key", apiKey)
        .GET()
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    if (response.statusCode() != 200) {
      throw new IOException("Unexpected response code: " + response.statusCode() + ", body: " + response.body());
    }

    return response.body();
  }
}

التحقّق من أزواج اسم الحزمة والملف المرجعي للشهادة

للتحقّق مما إذا كان اسم حزمة تطبيق مسجّلاً مع ملف مرجعي لشهادة SHA-256 العامة معيّنة، مرِّر مَعلمة طلب البحث certificateFingerprint:

الطلب:

curl -X GET "https://androiddeveloperidstatus.googleapis.com/v1/packages/com.example.app/packageRegistrationStatus:check?certificateFingerprint=d6ac89ed1d0a805aad4b087d06d5f41645b814480b133fbc867ef7498d069e06" \
  -H "X-Goog-Api-Key: [key]"

النتائج

الردّ (تم التسجيل باستخدام ملف مرجعي مطابق للشهادة):

إذا كان اسم الحزمة مسجّلاً مع الملف المرجعي لشهادة SHA-256 العامة المقدَّمة، ستتلقّى نص استجابة HTTP التالي مع رمز استجابة HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED"
}

الإجراء المقترَح: إذا كنت تجري هذا التحقّق نيابةً عن مطوّر آخر، أبلِغه بأنّ اسم الحزمة مسجَّل مع الملف المرجعي للشهادة المقدَّم.

الردّ (تم التسجيل باستخدام ملف مرجعي مختلف للشهادة):

إذا كان اسم الحزمة مسجّلاً مع ملف مرجعي مختلف لشهادة SHA-256 عن الملف المقدَّم، ستتلقّى نص استجابة HTTP التالي مع رمز استجابة HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED_WITH_ANOTHER_CERTIFICATE_FINGERPRINT"
}

الإجراء المقترَح: إذا كنت تجري هذا التحقّق نيابةً عن مطوّر آخر، أبلِغه بأنّ اسم الحزمة مسجَّل ولكن مع ملف مرجعي مختلف للشهادة عن الملف المقدَّم.

الردّ (لم يتم التسجيل):

إذا لم يكن اسم الحزمة مسجّلاً مع الملف المرجعي لشهادة SHA-256 العامة المقدَّمة، ستتلقّى نص استجابة HTTP التالي مع رمز استجابة HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "NOT_REGISTERED"
}

الإجراء المقترَح: إذا كنت تجري هذا التحقّق نيابةً عن مطوّر آخر، أبلِغه بأنّ اسم الحزمة غير مسجَّل مع الملف المرجعي للشهادة المقدَّم.

مثال بلغة Java

يتضمّن مثال Java هذا بشكلٍ صريح certificateFingerprint كمعلَمة طلب بحث بترميز عنوان URL للتحقّق من اقتران حزمة وملف مرجعي معيّنَين.

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class CheckPackageAndFingerprintClient {

  private static final String API_ENDPOINT = "https://androiddeveloperidstatus.googleapis.com";

  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY";
    String packageName = "com.example.app";
    String certificateFingerprint = "d6ac89ed1d0a805aad4b087d06d5f41645b814480b133fbc867ef7498d069e06";

    try {
      String response = checkPackageAndFingerprintRegistrationStatus(apiKey, packageName, certificateFingerprint);
      System.out.println("Response: " + response);
    } catch (IOException | InterruptedException e) {
      e.printStackTrace();
    }
  }

  /**
   *   Checks the registration status of a specific Android package and certificate fingerprint pair.
   */
  public static String checkPackageAndFingerprintRegistrationStatus(
      String apiKey, String packageName, String certificateFingerprint)
      throws IOException, InterruptedException {

    String path = String.format("/v1/packages/%s/packageRegistrationStatus:check", packageName);

    String encodedFingerprint = URLEncoder.encode(certificateFingerprint, StandardCharsets.UTF_8);
    String fullUrl = API_ENDPOINT + path + "?certificateFingerprint=" + encodedFingerprint;

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(fullUrl))
        .header("Accept", "application/json")
        .header("X-Goog-Api-Key", apiKey)
        .GET()
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    if (response.statusCode() != 200) {
      throw new IOException("Unexpected response code: " + response.statusCode() + ", body: " + response.body());
    }

    return response.body();
  }
}

فهم حالات التسجيل والتعامل مع الأخطاء

عندما يفشل طلب بيانات من واجهة برمجة التطبيقات، تعرض Android Developer ID Status API كائن خطأ JSON عاديًا من Google Cloud في نص الاستجابة. يوفر هذا الكائن بنية متّسقة لفهم الخطأ والتعامل معه.

مثال على استجابة الخطأ:

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

يحتوي كائن الخطأ على الحقول الرئيسية التالية:

• code: رمز حالة HTTP (على سبيل المثال، 400 أو 403 أو 500)
• message: وصف للخطأ باللغة الإنجليزية يظهر للمطوّر هذه الرسالة غير ثابتة ويمكن أن تتغيّر، لذا لا تنشئ منطق تحليل استنادًا إليها.
• status: رمز خطأ أساسي يحدّد نوع الخطأ آليًا (على سبيل المثال، INVALID_ARGUMENT أو PERMISSION_DENIED). يجب إنشاء منطق معالجة الأخطاء استنادًا إلى هذا المعرّف الثابت.

يسرد الجدول التالي الأخطاء الأكثر شيوعًا التي تعرضها واجهة برمجة التطبيقات والإجراء المقترَح.

سقف الحصص

يتم فرض حصص الاستخدام على أساس كل مشروع لضمان موثوقية الخدمة.

مراقبة استخدامك

يمكنك مراقبة الاستخدام الحالي لواجهة برمجة التطبيقات في مشروعك والاطّلاع على مدى اقترابك من حدود الحصص مباشرةً في Google Cloud Console.

1. انتقِل إلى صفحة واجهات برمجة التطبيقات والخدمات > لوحة البيانات.
2. اختَر Android Developer ID Status API.
3. انقر على علامة التبويب الحصص.

تقدّم لوحة البيانات هذه تفصيلاً دقيقًا لحجم طلباتك بمرور الوقت.