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

استخدِم واجهة برمجة التطبيقات Android Developer Status API للتحقّق مما إذا كان اسم حزمة تطبيق Android مسجّلاً لدى مطوّر تم التحقّق من هويته. إذا كنت تنشئ أدوات لتطوير البرامج أو بيئات تطوير متكاملة أو عمليات 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"
}

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

للتحقّق مما إذا كان اسم حزمة تطبيق مسجّلاً باستخدام ملف مرجعي لشهادة عامة محدّدة بتنسيق 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 التالية كيفية طلب البيانات من واجهة برمجة التطبيقات باستخدام HttpClient العادية في Java 11.

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 DeveloperIdStatusClient {

  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 = checkPackageRegistrationStatus(apiKey, packageName, certificateFingerprint);
      System.out.println("Response: " + response);
    } catch (IOException | InterruptedException e) {
      e.printStackTrace();
    }
  }

  /**
   *   Checks the registration status of an Android package.
   *
   *   @param apiKey The Google API key for authentication.
   *   @param packageName The fully-qualified Android package name (for example, "com.example.app").
   *   @param certificateFingerprint Optional SHA-256 certificate fingerprint. Pass null or empty to omit.
   *   @return The JSON response string from the API.
   */
  public static String checkPackageRegistrationStatus(
      String apiKey, String packageName, String certificateFingerprint)
      throws IOException, InterruptedException {

    // 1. Build the URL path (accepts dots directly)
    // Format: /v1/packages/{package}/packageRegistrationStatus:check
    String path = String.format("/v1/packages/%s/packageRegistrationStatus:check", packageName);

    // 2. Build query parameters (only certificateFingerprint if provided)
    StringBuilder queryBuilder = new StringBuilder();
    if (certificateFingerprint != null && !certificateFingerprint.isEmpty()) {
      queryBuilder.append("certificateFingerprint=")
          .append(URLEncoder.encode(certificateFingerprint, StandardCharsets.UTF_8));
    }

    String fullUrl = API_ENDPOINT + path;
    if (queryBuilder.length() > 0) {
      fullUrl += "?" + queryBuilder.toString();
    }

    // 3. Create and send the HTTP GET request with API Key header
    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".

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

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