Android Developer Console API

Android Developer Console API là một dịch vụ RESTful cho phép các nhà phát triển đã xác minh tự động hoá quy trình xác minh nhà phát triển Android trong Android Developer Console, bao gồm cả việc truy xuất tài khoản nhà phát triển, kiểm tra các yêu cầu chính về điều kiện, đăng ký tên gói Android, đăng ký khoá ký ứng dụng và xác minh quyền sở hữu khoá.

Tổng quan, trường hợp sử dụng và bối cảnh triển khai

Các trường hợp sử dụng và tính năng chính

• Đăng ký tên gói CI/CD tự động: Đăng ký hàng chục hoặc hàng trăm tên gói Android theo phương thức lập trình (CreateAndroidPackage).
• Kiểm tra chính sách khoá trước khi phát hành: Kiểm tra theo phương thức lập trình xem Google có từng ghi nhận tên gói trong hệ sinh thái hay không và liệu việc đăng ký một chứng chỉ ký cụ thể có yêu cầu xác minh quyền sở hữu khoá hay không (GetAndroidPackageRegistrationPolicy).
• Tự động đăng ký khoá ký ứng dụng và xác minh quyền sở hữu: Đăng ký vân tay số SHA-256 của chứng chỉ ký công khai (CreateAndroidPackageKey), truy xuất mã xác minh thử thách duy nhất (verificationToken) và tự động hoá quy trình chứng minh quyền sở hữu khoá riêng tư bằng cách sử dụng tính năng tải tệp APK đã ký lên theo yêu cầu duy nhất hoặc có thể tiếp tục (VerifyAndroidPackageKeyOwnership).
• Gửi lý do theo phương thức có lập trình: Gửi lý do chứng minh quyền sở hữu (JustifyAndroidPackageKeyRegistration).
• Theo dõi trạng thái: Theo dõi trạng thái đăng ký trên các tài khoản nhà phát triển, tên gói và khoá ký ứng dụng (GetDeveloperAccount, ListDeveloperAccounts, GetAndroidPackage, ListAndroidPackages, GetAndroidPackageKey, ListAndroidPackageKeys).

Quy trình triển khai toàn diện

1. Xác minh danh tính nhà phát triển một lần trong giao diện người dùng: Hoàn tất quy trình xác minh danh tính nhà phát triển (INDIVIDUAL hoặc ORGANIZATION) trong Android Developer Console để verificationState là VERIFIED.
2. Bật API và xác thực: Bật androiddeveloperconsole.googleapis.com trong dự án trên đám mây của Google Cloud và lấy mã truy cập Bearer OAuth 2.0 do người dùng uỷ quyền có phạm vi https://www.googleapis.com/auth/androiddeveloperconsole.
3. Tìm tên tài nguyên của tài khoản nhà phát triển: Gọi GET /v1/developerAccounts (ListDeveloperAccounts) để truy xuất developerAccounts/{developer_account} và xác minh verificationState là VERIFIED.
4. Kiểm tra chính sách đăng ký cho tên gói: Gọi GET /v1/developerAccounts/{id}/androidPackages/{pkg}/registrationPolicy (GetAndroidPackageRegistrationPolicy) để kiểm tra keySelectionStrategy (SELECT_KEY_FROM_LIST hoặc USE_ANY_KEY) và mọi khoá ký đã biết trong nhật ký (knownKeys).
5. Tạo tài nguyên gói Android: Gọi POST /v1/developerAccounts/{id}/androidPackages?androidPackageId={pkg} (CreateAndroidPackage) với nội dung {"name": ""} (tạo tài nguyên ở trạng thái DRAFT).
6. Đăng ký vân tay số của khoá ký ứng dụng: Gọi POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys (CreateAndroidPackageKey) bằng nội dung JSON {"certificateFingerprintSha256": "..."}. Kiểm tra trạng thái được trả về:
   • DRAFT: Bạn phải cung cấp bằng chứng về quyền sở hữu khoá riêng tư và phản hồi sẽ bao gồm một verificationToken duy nhất cho Bước 7.
   • IN_REVIEW: Bằng chứng chứng minh quyền sở hữu và lý do sẽ tự động được bỏ qua (ví dụ: khi đăng ký tên gói mới chưa từng xuất hiện trên Android hoặc khi bạn đã xác minh quyền sở hữu khoá ký này cho một tên gói khác trong cùng một DeveloperAccount). Bỏ qua Bước 7 và lệnh gọi lý do ở Bước 8, rồi chuyển thẳng đến lệnh gọi thăm dò ý kiến GetAndroidPackage và GetAndroidPackageKey.
7. Tạo và tải APK xác minh lên (nếu trạng thái là DRAFT): Nhúng chuỗi verificationToken được trả về vào assets/adi-registration.properties bên trong một APK tối thiểu khớp với packageName, ký APK đó bằng khoá ký ứng dụng riêng tư của bạn rồi tải APK đó lên bằng POST /upload/v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:verify (VerifyAndroidPackageKeyOwnership).
8. Gửi lý do (nếu cần) và thăm dò trạng thái đăng ký: Nếu khoá ở trạng thái OWNERSHIP_VERIFIED và registrationJustificationRequired là true, hãy gọi POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:justifyAndroidPackageKeyRegistration (JustifyAndroidPackageKeyRegistration). Thăm dò GetAndroidPackage và GetAndroidPackageKey cho đến khi state đạt REGISTERED.

Các lệnh CLI cục bộ để chuẩn bị dấu vân tay khoá và APK xác minh

• Trích xuất dấu vân tay chứng chỉ SHA-256 từ kho khoá (keytool):

  keytool -list -v -keystore release-key.jks -alias my-key-alias

• Xác minh chuỗi đại diện chứng chỉ ký SHA-256 trên một tệp APK đã tạo (apksigner):

  apksigner verify --print-certs app-release.apk

• Kiểm tra tên gói APK và tệp mã thông báo được nhúng trước khi tải lên (aapt2 và unzip):

  aapt2 dump badging app-release.apk | head -n 1
  unzip -p app-release.apk assets/adi-registration.properties

Giao diện người dùng và các chức năng API của Android Developer Console

Cấu hình và xác thực dịch vụ

Tất cả yêu cầu API đều phải sử dụng HTTPS và bao gồm một tiêu đề Authorization: Bearer ACCESS_TOKEN có được bằng cách sử dụng quy trình Máy chủ web OAuth 2.0 cho một Tài khoản Google đã hoàn tất quy trình xác minh danh tính nhà phát triển trong Android Developer Console.

Tài nguyên và điểm cuối API

Android Developer Console API sắp xếp tài nguyên theo hệ phân cấp sau:

• DeveloperAccount (developerAccounts/{developer_account})
  • AndroidPackage (developerAccounts/{developer_account}/androidPackages/{android_package})
    • AndroidPackageRegistrationPolicy (developerAccounts/{developer_account}/androidPackages/{android_package}/registrationPolicy)
    • AndroidPackageKey (developerAccounts/{developer_account}/androidPackages/{android_package}/keys/{key})

Tài nguyên: DeveloperAccount

Đại diện cho một tài khoản trong Android Developer Console được liên kết với danh tính của nhà phát triển.

Enum: DeveloperAccount.VerificationState

Phương thức: DeveloperAccount

Tài nguyên: AndroidPackage

Đại diện cho tên gói Android đã đăng ký hoặc đang được đăng ký trong một DeveloperAccount.

Enum: AndroidPackage.State

Tài nguyên: AndroidPackageRegistrationPolicy

Tài nguyên đơn lẻ do GetAndroidPackageRegistrationPolicy trả về, mô tả các khoá ký công khai trước đây được phát hiện cho một tên gói và liệu việc đăng ký tên gói bằng một khoá ký nhất định có cần phải có lý do bằng văn bản hay không.

Enum: KnownKey.JustificationRequirement

Enum: AndroidPackageRegistrationPolicy.KeySelectionStrategy

Phương thức: AndroidPackage

Tài nguyên: AndroidPackageKey

Đại diện cho dấu vân tay chứng chỉ ký ứng dụng công khai liên kết với một AndroidPackage, đồng thời theo dõi trạng thái xem xét việc đăng ký và xác minh quyền sở hữu.

Enum: AndroidPackageKey.State

Phương thức: AndroidPackageKey

Xử lý lỗi

Khi một yêu cầu API không thành công, Android Developer Console API sẽ trả về mã trạng thái HTTP 4xx hoặc 5xx và nội dung lỗi JSON google.rpc.Status chuẩn:

{
  "error": {
    "code": 400,
    "message": "Invalid certificate fingerprint SHA256 format.",
    "status": "INVALID_ARGUMENT",
    "details": []
  }
}

Mã trạng thái HTTP và cách giải quyết phổ biến

Ví dụ về yêu cầu và phản hồi HTTP

Thay thế các giá trị phần giữ chỗ như ACCESS_TOKEN, 1234567890, com.example.myapp và 60e860e8... bằng giá trị của riêng bạn.

1. GetDeveloperAccount

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890"

Câu trả lời:

{
  "name": "developerAccounts/1234567890",
  "displayName": "Example Developer",
  "verificationState": "VERIFIED"
}

2. ListDeveloperAccounts

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts"

Câu trả lời:

{
  "developerAccounts": [
    {
      "name": "developerAccounts/1234567890",
      "displayName": "Example Developer",
      "verificationState": "VERIFIED"
    }
  ]
}

3. GetAndroidPackageRegistrationPolicy

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/registrationPolicy"

Câu trả lời:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/registrationPolicy",
  "knownKeys": [
    {
      "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
      "justificationRequirement": "NOT_REQUIRED"
    }
  ],
  "keySelectionStrategy": "SELECT_KEY_FROM_LIST"
}

4. CreateAndroidPackage

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"name": ""}' \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages?androidPackageId=com.example.myapp"

Câu trả lời:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp",
  "packageName": "com.example.myapp",
  "state": "DRAFT",
  "registeredAppStore": false
}

5. GetAndroidPackage

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp"

Câu trả lời:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp",
  "packageName": "com.example.myapp",
  "state": "REGISTERED",
  "registeredAppStore": false
}

6. ListAndroidPackages

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages?pageSize=100"

Câu trả lời:

{
  "androidPackages": [
    {
      "name": "developerAccounts/1234567890/androidPackages/com.example.myapp",
      "packageName": "com.example.myapp",
      "state": "REGISTERED",
      "registeredAppStore": false
    }
  ],
  "nextPageToken": ""
}

7. CreateAndroidPackageKey

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123"
  }' \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys"

Câu trả lời:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "DRAFT",
  "verificationToken": "token_xyz987654321"
}

8. GetAndroidPackageKey

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123"

Câu trả lời:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "REGISTERED"
}

9. ListAndroidPackageKeys

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys?pageSize=100"

Câu trả lời:

{
  "androidPackageKeys": [
    {
      "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
      "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
      "state": "REGISTERED"
    }
  ],
  "nextPageToken": ""
}

10. VerifyAndroidPackageKeyOwnership

Cách A: Tải nội dung nghe nhìn lên bằng một yêu cầu duy nhất

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @app-release.apk \
  "https://androiddeveloperconsole.googleapis.com/upload/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123:verify?uploadType=media"

Cách B: Giao thức tải lên có thể tiếp tục (nên dùng cho các tệp APK lớn hoặc CI/CD)

Bước 1: Bắt đầu phiên tải lên có thể tiếp tục và trích xuất tiêu đề X-Goog-Upload-URL được trả về:

curl -i -X POST \
  "https://androiddeveloperconsole.googleapis.com/upload/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123:verify" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: FILE_SIZE_IN_BYTES" \
  -H "X-Goog-Upload-Header-Content-Type: application/vnd.android.package-archive" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123"
  }'

Bước 2: Tải tệp nhị phân APK đã ký lên UPLOAD_SESSION_URI và hoàn tất phiên:

curl -X PUT \
  "UPLOAD_SESSION_URI" \
  -H "Content-Length: FILE_SIZE_IN_BYTES" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@app-release.apk"

Câu trả lời:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "IN_REVIEW"
}

11. JustifyAndroidPackageKeyRegistration

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "justification": "We previously distributed com.example.myapp directly from https://downloads.example.com and are migrating to our rotated production key."
  }' \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123:justifyAndroidPackageKeyRegistration"

Câu trả lời:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "IN_REVIEW",
  "registrationJustificationRequired": true
}

Tài nguyên khác

• Đăng ký tên gói bằng API Android Developer Console
• Kiểm tra trạng thái đăng ký ứng dụng bằng Android Developer ID Status API
• Đăng ký trên Android Developer Console
• Đăng ký trên Google Play Console