Android Developer Console API

Android Developer Console API to usługa RESTful, która umożliwia zweryfikowanym deweloperom automatyzację procesów weryfikacji dewelopera aplikacji na Androida w Konsoli programisty Androida, w tym pobieranie kont deweloperów, sprawdzanie kluczowych wymagań, rejestrowanie nazw pakietów aplikacji na Androida, rejestrowanie kluczy podpisywania aplikacji i weryfikowanie własności kluczy.

Omówienie, przypadki użycia i kontekst implementacji

Najważniejsze przypadki użycia i funkcje

• Automatyczna rejestracja nazw pakietów CI/CD: rejestruj dziesiątki lub setki nazw pakietów na Androida automatycznie (CreateAndroidPackage).
• Wstępna kontrola historycznych zasad dotyczących kluczy: automatyczne sprawdzanie, czy nazwa pakietu była już wcześniej widoczna w ekosystemie Google i czy zarejestrowanie konkretnego certyfikatu podpisywania wymaga weryfikacji własności klucza (GetAndroidPackageRegistrationPolicy).
• Automatyczna rejestracja klucza podpisywania aplikacji i weryfikacja własności: zarejestruj odciski cyfrowe SHA-256 publicznego certyfikatu podpisywania (CreateAndroidPackageKey), pobierz unikalne tokeny wyzwania weryfikacyjnego (verificationToken) i zautomatyzuj potwierdzanie posiadania klucza prywatnego za pomocą przesyłania podpisanych plików APK w ramach pojedynczego żądania lub z możliwością wznowienia (VerifyAndroidPackageKeyOwnership).
• Przesyłanie uzasadnienia automatycznego: prześlij uzasadnienia własności (JustifyAndroidPackageKeyRegistration).
• Monitorowanie stanu: monitoruj stan rejestracji na kontach deweloperów, nazwy pakietów i klucze podpisywania aplikacji (GetDeveloperAccount, ListDeveloperAccounts, GetAndroidPackage, ListAndroidPackages, GetAndroidPackageKey, ListAndroidPackageKeys).

Kompleksowy proces implementacji

1. Jednorazowa weryfikacja tożsamości dewelopera w interfejsie: przeprowadź weryfikację tożsamości dewelopera (INDIVIDUAL lub ORGANIZATION) w Konsoli programisty Androida, aby verificationState była VERIFIED.
2. Włącz interfejs API i przeprowadź uwierzytelnianie: włącz androiddeveloperconsole.googleapis.com w projekcie Google Cloud i uzyskaj token dostępu na okaziciela OAuth 2.0 przekazany przez użytkownika z zakresem https://www.googleapis.com/auth/androiddeveloperconsole.
3. Znajdź nazwę zasobu konta dewelopera: wywołaj GET /v1/developerAccounts (ListDeveloperAccounts), aby pobrać developerAccounts/{developer_account} i sprawdzić, czy verificationState to VERIFIED.
4. Sprawdź zasady rejestracji nazwy pakietu: wywołaj GET /v1/developerAccounts/{id}/androidPackages/{pkg}/registrationPolicy (GetAndroidPackageRegistrationPolicy), aby sprawdzić keySelectionStrategy (SELECT_KEY_FROM_LIST lub USE_ANY_KEY) i wszystkie znane historyczne klucze do podpisywania (knownKeys).
5. Utwórz zasób pakietu Androida: wywołaj POST /v1/developerAccounts/{id}/androidPackages?androidPackageId={pkg} (CreateAndroidPackage) z treścią {"name": ""} (tworzy zasób w stanie DRAFT).
6. Zarejestruj odcisk cyfrowy klucza podpisywania aplikacji: wywołaj POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys (CreateAndroidPackageKey) z treścią JSON {"certificateFingerprintSha256": "..."}. Sprawdź zwrócony stan:
   • DRAFT: wymagany jest dowód własności klucza prywatnego, a odpowiedź zawiera unikalny identyfikator verificationToken dla kroku 7.
   • IN_REVIEW: dowód własności i uzasadnienie są pomijane automatycznie (np. podczas rejestrowania nowej nazwy pakietu, która nigdy nie była używana na Androidzie, lub gdy własność tego klucza podpisywania została już zweryfikowana w przypadku innej nazwy pakietu w tym samym DeveloperAccount). Pomiń krok 7 i wywołanie uzasadnienia w kroku 8 i przejdź bezpośrednio do odpytywania GetAndroidPackage i GetAndroidPackageKey.
7. Utwórz i prześlij plik APK do weryfikacji (jeśli stan to DRAFT): umieść zwrócony ciąg znaków verificationToken w assets/adi-registration.properties w minimalnym pliku APK pasującym do packageName, podpisz go prywatnym kluczem podpisywania aplikacji i prześlij za pomocą POST /upload/v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:verify (VerifyAndroidPackageKeyOwnership).
8. Prześlij uzasadnienie (jeśli jest wymagane) i sprawdź stan rejestracji: jeśli klucz jest w stanie OWNERSHIP_VERIFIED, a registrationJustificationRequired to true, wywołaj POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:justifyAndroidPackageKeyRegistration (JustifyAndroidPackageKeyRegistration). Sprawdzaj GetAndroidPackage i GetAndroidPackageKey, aż state osiągnie stan REGISTERED.

Lokalne polecenia interfejsu wiersza poleceń do przygotowywania odcisków cyfrowych kluczy i plików APK do weryfikacji

• Wyodrębnianie odcisku cyfrowego certyfikatu SHA-256 z magazynu kluczy (keytool):

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

• Sprawdź skrót certyfikatu podpisywania SHA-256 w utworzonym pakiecie APK (apksigner):

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

• Sprawdź nazwę pakietu APK i wbudowany plik tokena przed przesłaniem (aapt2 i unzip):

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

Interfejs Konsoli programisty Androida i funkcje interfejsu API

Konfiguracja usługi i uwierzytelnianie

Wszystkie żądania do interfejsu API muszą używać protokołu HTTPS i zawierać nagłówek Authorization: Bearer ACCESS_TOKEN uzyskany za pomocą procesu serwera WWW OAuth 2.0 dla konta Google, które przeszło weryfikację tożsamości dewelopera w Konsoli programisty Androida.

Zasoby i punkty końcowe interfejsu API

Interfejs API Konsoli programisty Androida porządkuje zasoby w następującej hierarchii:

• 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})

Zasób: DeveloperAccount

Reprezentuje konto w Konsoli programisty Androida powiązane z tożsamością dewelopera.

Enum: DeveloperAccount.VerificationState

Metody: DeveloperAccount

Zasób: AndroidPackage

Reprezentuje nazwę pakietu na Androida zarejestrowaną lub rejestrowaną w DeveloperAccount.

Typ wyliczeniowy: AndroidPackage.State

Zasób: AndroidPackageRegistrationPolicy

Zasób typu singleton zwracany przez GetAndroidPackageRegistrationPolicy, który opisuje historyczne publiczne klucze podpisywania wykryte dla nazwy pakietu i określa, czy zarejestrowanie nazwy pakietu z danym kluczem podpisywania wymaga pisemnego uzasadnienia.

Typ wyliczeniowy: KnownKey.JustificationRequirement

Typ wyliczeniowy: AndroidPackageRegistrationPolicy.KeySelectionStrategy

Metody: AndroidPackage

Zasób: AndroidPackageKey

Reprezentuje odcisk cyfrowy publicznego certyfikatu podpisywania aplikacji powiązany z AndroidPackage i śledzi stan weryfikacji własności oraz sprawdzania rejestracji.

Typ wyliczeniowy: AndroidPackageKey.State

Metody: AndroidPackageKey

Obsługa błędów

Gdy żądanie do interfejsu API się nie powiedzie, interfejs API Konsoli programisty Androida zwraca kod stanu HTTP 4xx lub 5xx oraz standardową treść błędu JSON google.rpc.Status:

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

Kody stanu HTTP i typowe rozwiązania

Przykłady żądań i odpowiedzi HTTP

Zastąp wartości zmiennych, takie jak ACCESS_TOKEN, 1234567890, com.example.myapp i 60e860e8..., własnymi wartościami.

1. GetDeveloperAccount

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

Odpowiedź:

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

2. ListDeveloperAccounts

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

Odpowiedź:

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

Odpowiedź:

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

Odpowiedź:

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

Odpowiedź:

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

Odpowiedź:

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

Odpowiedź:

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

Odpowiedź:

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

Odpowiedź:

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

10. VerifyAndroidPackageKeyOwnership

Opcja A. Przesyłanie multimediów za pomocą pojedynczego żądania

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"

Opcja B. Protokół przesyłania z możliwością wznowienia (zalecany w przypadku dużych plików APK lub CI/CD)

Krok 1. Rozpocznij sesję przesyłania z możliwością wznowienia i wyodrębnij zwrócony nagłówek X-Goog-Upload-URL:

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"
  }'

Krok 2. Prześlij podpisany plik binarny APK do UPLOAD_SESSION_URI i sfinalizuj sesję:

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"

Odpowiedź:

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

Odpowiedź:

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

Dodatkowe materiały

• Rejestrowanie nazw pakietów za pomocą interfejsu API Konsoli programisty Androida
• Sprawdzanie stanu rejestracji aplikacji za pomocą interfejsu Android Developer ID Status API
• Rejestracja w Konsoli programisty Androida
• Rejestracja w Konsoli Google Play