Kiểm tra trạng thái đăng ký ứng dụng bằng Android Developer ID Status API

Sử dụng Android Developer Status API để kiểm tra xem tên gói ứng dụng Android có được đăng ký với một nhà phát triển đã xác minh hay không. Nếu tạo các công cụ phát triển phần mềm, IDE hoặc quy trình CI/CD tự động, bạn có thể tích hợp API từ máy chủ đến máy chủ này để làm những việc sau:

• Kiểm tra xem tên gói ứng dụng có được đăng ký cho một nhà phát triển đã xác minh hay không
• Xác thực xem vân tay SHA-256 của chứng chỉ ký của ứng dụng có khớp với thông tin xác thực trong tệp cho tên gói đã đăng ký hay không
• Nhắc nhà phát triển trong giao diện của công cụ đăng ký các ứng dụng không xác định trong chương trình xác minh nhà phát triển Android

API này được thiết kế để hỗ trợ nhiều quy trình làm việc của nhà phát triển:

Hướng dẫn này giải thích cách hoàn tất các thao tác sau:

1. Thiết lập quyền truy cập và xác thực API Google Cloud.
2. Xác minh xem một cặp tên gói và dấu vân tay chứng chỉ công khai SHA-256 của ứng dụng đã được nhà phát triển đã xác minh đăng ký trong chương trình xác minh nhà phát triển Android hay chưa, bằng dấu vân tay chứng chỉ công khai SHA-256 được cung cấp hoặc một dấu vân tay chứng chỉ công khai SHA-256 khác.
3. Xử lý các trạng thái đăng ký API trong quy trình làm việc của IDE hoặc công cụ dành cho nhà phát triển.

Điều kiện tiên quyết

Tài liệu này dành cho nhà phát triển ứng dụng Android hoặc nhà phát triển công cụ phát triển phần mềm. Trước khi bắt đầu, bạn cần có:

• Quyền truy cập quản trị vào một dự án trên Google Cloud.
• Có kiến thức cơ bản về API RESTful, JSON và dấu vân tay chứng chỉ SHA-256.

Bạn cũng cần nắm rõ các thuật ngữ sau:

Điểm cuối dịch vụ

Điểm cuối dịch vụ là một URL cơ sở chỉ định địa chỉ mạng của một dịch vụ API. Dịch vụ này có điểm cuối dịch vụ sau và tất cả URI đều liên quan đến điểm cuối dịch vụ này:

https://androiddeveloperidstatus.googleapis.com

Bật API

Để sử dụng Android Developer ID Status API, bạn phải hoàn tất các bước thiết lập để tạo một dự án và bật API này.

Tạo một dự án trên Google Cloud

1. Tạo một Tài khoản Google Cloud nếu bạn chưa có.
2. Mở Google Cloud Console.
3. Tạo một dự án trên Google Cloud.

Bật API trong dự án của bạn

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến API và dịch vụ > Thư viện.
2. Chọn dự án của bạn trong trình đơn thả xuống.
3. Tìm kiếm Android Developer ID Status API.
4. Nhấp vào Bật.

Xác thực

API này hỗ trợ thông tin xác thực khoá API. Cách lấy khoá API:

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến API và Dịch vụ > Thông tin xác thực.
2. Nhấp vào + Tạo thông tin xác thực rồi chọn Khoá API.
3. Định cấu hình khoá rồi sao chép khoá đó. Sử dụng khoá này trong tiêu đề yêu cầu.

Kiểm tra trạng thái đăng ký ứng dụng

Bạn có thể truy vấn tài nguyên PackageRegistrationStatus để chỉ xác minh tên gói hoặc kiểm tra tên gói được ghép nối với một dấu vân tay chứng chỉ cụ thể.

Kiểm tra tên gói

Để kiểm tra xem tên gói ứng dụng có được nhà phát triển đã xác minh nào đăng ký hay không, hãy thực hiện một yêu cầu GET đã xác thực có chứa tên gói của ứng dụng Android (ví dụ: com.example.app) đến điểm cuối packageRegistrationStatus:check mà không có các tham số không bắt buộc:

Yêu cầu:

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

Kết quả

Phản hồi (Đã đăng ký):

Nếu tên gói đã được đăng ký, bạn sẽ nhận được nội dung phản hồi HTTP sau đây với mã phản hồi HTTP 200:

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

Hành động được đề xuất: Thông báo cho nhà phát triển rằng tên gói đã được đăng ký.

Phản hồi (Chưa đăng ký):

Nếu tên gói chưa được đăng ký, bạn sẽ nhận được nội dung phản hồi HTTP sau đây với mã phản hồi HTTP 200:

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

Xác minh các cặp tên gói và dấu vân tay chứng chỉ

Để kiểm tra xem tên gói ứng dụng có được đăng ký bằng dấu vân tay SHA-256 của một chứng chỉ công khai cụ thể hay không, hãy truyền tham số truy vấn certificateFingerprint:

Yêu cầu:

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

Kết quả

Phản hồi (Đã đăng ký bằng dấu vân tay chứng chỉ trùng khớp):

Nếu tên gói được đăng ký bằng dấu vân tay SHA-256 của chứng chỉ công khai được cung cấp, thì bạn sẽ nhận được nội dung phản hồi HTTP sau đây với mã phản hồi HTTP 200:

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

Phản hồi (Đã đăng ký bằng dấu vân tay chứng chỉ khác):

Nếu tên gói được đăng ký bằng một dấu vân tay SHA-256 của chứng chỉ khác với dấu vân tay được cung cấp, thì bạn sẽ nhận được nội dung phản hồi HTTP sau đây với mã phản hồi HTTP 200:

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

Phản hồi (Chưa đăng ký):

Nếu tên gói không được đăng ký bằng dấu vân tay SHA-256 của chứng chỉ công khai được cung cấp, bạn sẽ nhận được nội dung phản hồi HTTP sau đây với mã phản hồi HTTP 200:

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

Ví dụ về cách triển khai Java

Lớp Java sau đây minh hoạ cách gọi API bằng HttpClient tiêu chuẩn của 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();
  }
}

Tìm hiểu về trạng thái đăng ký và cách xử lý lỗi

Khi một yêu cầu API không thành công, Android Developer ID Status API sẽ trả về một đối tượng lỗi JSON tiêu chuẩn của Google Cloud trong nội dung phản hồi. Đối tượng này cung cấp một cấu trúc nhất quán để hiểu và xử lý lỗi.

Ví dụ về phản hồi lỗi:

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

Đối tượng lỗi chứa các trường khoá sau:

• code: Mã trạng thái HTTP (ví dụ: 400, 403, 500).
• message: Nội dung mô tả lỗi bằng tiếng Anh dành cho nhà phát triển. Thông báo này không ổn định và có thể thay đổi, vì vậy, đừng xây dựng logic phân tích cú pháp xung quanh thông báo này.
• status: Mã lỗi chuẩn xác xác định theo chương trình loại lỗi (ví dụ: INVALID_ARGUMENT, PERMISSION_DENIED). Bạn nên xây dựng logic xử lý lỗi dựa trên giá trị nhận dạng ổn định này.

Bảng sau đây liệt kê các lỗi phổ biến nhất mà API trả về và cách xử lý được đề xuất.

Hạn mức

Hạn mức sử dụng được áp dụng cho từng dự án để đảm bảo độ tin cậy của dịch vụ.

Theo dõi mức sử dụng

Bạn có thể theo dõi mức sử dụng API hiện tại của dự án và xem mức sử dụng đã gần đến giới hạn hạn mức hay chưa ngay trong Google Cloud Console.

1. Chuyển đến trang API và dịch vụ > Trang tổng quan.
2. Chọn Android Developer ID Status API.
3. Nhấp vào thẻ Hạn mức.

Trang tổng quan này cung cấp thông tin chi tiết về số lượng yêu cầu theo thời gian.