בדיקת סטטוס הרישום של האפליקציה באמצעות Android Developer ID Status API

אפשר להשתמש ב-API של סטטוס המפתחים ב-Android כדי לבדוק אם שם חבילה של אפליקציית Android רשום אצל מפתח מאומת. אם אתם בונים כלים לפיתוח תוכנה, סביבות פיתוח משולבות (IDE) או תהליכי עבודה אוטומטיים של CI/CD, אתם יכולים לשלב את ה-API הזה של שרת לשרת כדי לבצע את הפעולות הבאות:

• איך בודקים אם שם חבילת APK רשום על שם מפתח מאומת
• בדיקה אם טביעת האצבע מסוג SHA-256 של אישור החתימה של האפליקציה תואמת לפרטי הכניסה שרשומים בקובץ עבור שם החבילה הרשום
• להציג למפתחים בממשק של הכלי הנחיה לרשום אפליקציות לא מזוהות בתוכנית האימות למפתחים ב-Android

הממשק הזה נועד לתמוך בתהליכי עבודה שונים של מפתחים:

במדריך הזה מוסבר איך לבצע את הפעולות הבאות:

1. הגדרת גישה ואימות של Google Cloud API.
2. כדי לבדוק אם שם החבילה של אפליקציה וטביעת האצבע מסוג SHA-256 של האישור הציבורי שלה נרשמו בתוכנית לאימות מפתחים ב-Android על ידי מפתח מאומת, אפשר להשתמש בטביעת האצבע מסוג SHA-256 של האישור הציבורי שסופקה או בטביעת אצבע אחרת מסוג SHA-256 של אישור ציבורי.
3. טיפול במצבי רישום של API בסביבת הפיתוח המשולבת או בתהליך העבודה של כלי הפיתוח.

דרישות מוקדמות

המסמך הזה מיועד למפתחי אפליקציות ל-Android או למפתחי כלים לפיתוח תוכנה. לפני שמתחילים, צריך:

• גישת אדמין לפרויקט בענן ב-Google Cloud.
• הבנה בסיסית של ממשקי API מסוג RESTful,‏ JSON וטביעות אצבע של אישורי SHA-256.

חשוב גם להכיר את המונחים הבאים:

נקודת קצה של שירות

נקודת קצה של שירות היא כתובת URL בסיסית שמציינת את כתובת הרשת של שירות API. לשירות הזה יש את נקודת הקצה הבאה, וכל כתובות ה-URI הן יחסיות לנקודת הקצה הזו:

https://androiddeveloperidstatus.googleapis.com

הפעלת ה-API

כדי להשתמש ב-Android Developer ID Status API, צריך להשלים את שלבי ההגדרה ליצירת פרויקט ולהפעלת ה-API.

יצירת פרויקט של Google Cloud

1. אם אין לכם חשבון Google Cloud, אתם צריכים ליצור חשבון.
2. פותחים את מסוף Google Cloud.
3. יוצרים פרויקט ב-Google Cloud.

הפעלת ה-API בפרויקט

1. במסוף Google Cloud, עוברים אל APIs & Services > Library.
2. בוחרים את הפרויקט מהתפריט הנפתח.
3. מחפשים את Android Developer ID Status API.
4. לוחצים על הפעלה.

אימות

ממשק ה-API תומך בפרטי כניסה של מפתח API. כדי לקבל מפתח API:

1. במסוף Google Cloud, עוברים אל APIs & Services > Credentials.
2. לוחצים על + Create credentials (יצירת פרטי כניסה) ובוחרים באפשרות API key (מפתח API).
3. מגדירים את המפתח ומעתיקים אותו. משתמשים במפתח הזה בכותרות של הבקשה.

בדיקת סטטוס הרישום של האפליקציה

אפשר לשלוח שאילתה למשאב PackageRegistrationStatus כדי לאמת רק שם חבילה, או לבדוק שם חבילה שמשויך לטביעת אצבע לאישור ספציפית.

בדיקת שם חבילה

כדי לבדוק אם שם חבילת APK רשום על ידי מפתח מאומת, צריך לשלוח בקשה מאומתת GET שמכילה את שם חבילת ה-APK של אפליקציית 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 הבא עם קוד התגובה 200 של HTTP:

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

פעולה מומלצת: צריך להודיע למפתח ששם החבילה כבר רשום.

תשובה (לא רשום):

אם שם החבילה לא רשום, תקבלו את גוף תגובת ה-HTTP הבא עם קוד התגובה 200 של HTTP:

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

אימות של זוגות של שם חבילה וטביעת אצבע לאישור

כדי לבדוק אם שם חבילת APK רשום עם טביעת אצבע ספציפית של אישור ציבורי מסוג 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 הבא עם קוד התגובה 200 של HTTP:

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

תשובה (נרשם עם טביעת אצבע שונה של אישור):

אם שם החבילה רשום עם טביעת אצבע שונה של אישור SHA-256 מזו שסופקה, תקבלו את גוף תגובת ה-HTTP הבא עם קוד התגובה 200 של HTTP:

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

תשובה (לא רשום):

אם שם החבילה לא רשום עם טביעת האצבע של אישור ה-SHA-256 הציבורי שסופק, תקבלו את גוף התשובה הבא של HTTP עם קוד התשובה 200 של HTTP:

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

דוגמה להטמעה ב-Java

במחלקת Java הבאה מוצג אופן ההפעלה של ה-API באמצעות 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();
  }
}

הסבר על מצבי רישום וטיפול בשגיאות

אם בקשת API נכשלת, ה-Android Developer ID Status API מחזיר אובייקט שגיאה סטנדרטי של Google Cloud JSON בגוף התגובה. האובייקט הזה מספק מבנה עקבי להבנה ולטיפול בשגיאה.

דוגמה לתגובת שגיאה:

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

אובייקט השגיאה מכיל את שדות המפתח הבאים:

• ‫code: קוד סטטוס של HTTP (לדוגמה, 400, ‏ 403, ‏ 500).
• ‫message: תיאור השגיאה באנגלית שמוצג למפתחים. ההודעה הזו לא יציבה ויכולה להשתנות, לכן לא כדאי לבנות סביבה לוגיקה של ניתוח נתונים.
• ‫status: קוד שגיאה קנוני שמזהה באופן פרוגרמטי את סוג השגיאה (לדוגמה, INVALID_ARGUMENT, ‏ PERMISSION_DENIED). לוגיקת הטיפול בשגיאות צריכה להתבסס על המזהה היציב הזה.

בטבלה הבאה מפורטות השגיאות הנפוצות ביותר שמוחזרות על ידי ה-API ומומלץ לפעול לפי ההנחיות לפתרון שלהן.

מגבלות המכסה

מכסות השימוש נאכפות לכל פרויקט בנפרד כדי להבטיח את מהימנות השירות.

מעקב אחר השימוש

אתם יכולים לעקוב אחרי השימוש הנוכחי ב-API בפרויקט ולראות כמה אתם קרובים למגבלות המכסה ישירות במסוף Google Cloud.

1. עוברים לדף APIs & Services > Dashboard (ממשקי API ושירותים > מרכז בקרה).
2. בוחרים באפשרות Android Developer ID Status API.
3. לוחצים על הכרטיסייה Quotas (מכסות).

בלוח הבקרה הזה מוצג פירוט של נפח הבקשות לאורך זמן.