Android Developer Console API

Android Developer Console API یک سرویس RESTful است که به توسعه‌دهندگان درستی‌سنجی‌شده امکان می‌دهد گردش‌های کاری درستی‌سنجی توسعه‌دهنده Android را در Android Developer Console خودکارسازی کنند، ازجمله بازیابی حساب‌های توسعه‌دهنده، بررسی الزامات واجدشرایط بودن کلید، ثبت نام بسته‌های Android، ثبت کلیدهای امضای برنامه، و درستی‌سنجی مالکیت کلید.

نمای کلی، موارد استفاده، و بافت پیاده‌سازی

موارد استفاده و ویژگی‌های کلیدی

• ثبت خودکار نام بسته CI/CD: ده‌ها یا صدها نام بسته Android را به‌صورت برنامه‌نویسی‌شده ثبت کنید (CreateAndroidPackage).
• بازرسی خط‌مشی کلید سابقه پیش‌پرواز: به‌صورت برنامه‌نویسی‌شده بازرسی می‌کند که آیا Google قبلاً نام بسته‌ای را در بوم‌سازگان مشاهده کرده است یا نه و آیا ثبت گواهی امضای خاصی به درستی‌سنجی مالکیت کلید نیاز دارد یا نه (GetAndroidPackageRegistrationPolicy).
• ثبت خودکار کلید امضای برنامه و درستی‌سنجی مالکیت: اثر انگشت‌های SHA-256 گواهی امضای عمومی را ثبت کنید (CreateAndroidPackageKey)، کدهای چالش درستی‌سنجی منحصربه‌فرد را بازیابی کنید (verificationToken)، و اثبات مالکیت کلید خصوصی را بااستفاده از بارگذاری‌های APK امضاشده ازسرگرفتنی یا تک‌درخواستی خودکار کنید (VerifyAndroidPackageKeyOwnership).
• ارسال توجیه برنامه‌ای: توجیه مالکیت ارسال کنید (JustifyAndroidPackageKeyRegistration).
• پایش وضعیت: پایش وضعیت ثبت در حساب‌های توسعه‌دهنده، نام‌های بسته، و کلیدهای امضای برنامه (GetDeveloperAccount، ListDeveloperAccounts، GetAndroidPackage، ListAndroidPackages، GetAndroidPackageKey، ListAndroidPackageKeys).

گردش کار پیاده‌سازی سرتاسر

1. درستی‌سنجی هویت توسعه‌دهنده یک‌بار در میانای کاربر: درستی‌سنجی هویت توسعه‌دهنده (INDIVIDUAL یا ORGANIZATION) را در Android Developer Console تکمیل کنید تا verificationState VERIFIED شود.
2. فعال کردن میانای برنامه‌سازی کاربردی و اصالت‌سنجی: androiddeveloperconsole.googleapis.com را در پروژه Google Cloud خود فعال کنید و یک کد دسترسی OAuth 2.0 Bearer با واگذاری کاربر با محدوده https://www.googleapis.com/auth/androiddeveloperconsole دریافت کنید.
3. نام منبع حساب توسعه‌دهنده خود را پیدا کنید: با GET /v1/developerAccounts (ListDeveloperAccounts) تماس بگیرید تا developerAccounts/{developer_account} را بازیابی کنید و تأیید کنید که verificationState VERIFIED است.
4. خط‌مشی ثبت نام بسته را بررسی کنید: با GET /v1/developerAccounts/{id}/androidPackages/{pkg}/registrationPolicy (GetAndroidPackageRegistrationPolicy) تماس بگیرید تا keySelectionStrategy (SELECT_KEY_FROM_LIST یا USE_ANY_KEY) و هرگونه کلید امضای شناخته‌شده قبلی (knownKeys) را بررسی کنید.
5. منبع بسته Android را ایجاد کنید: با بدنه {"name": ""} با POST /v1/developerAccounts/{id}/androidPackages?androidPackageId={pkg} (CreateAndroidPackage) تماس بگیرید (منبع را در وضعیت DRAFT ایجاد می‌کند).
6. اثر انگشت کلید امضای برنامه‌تان را ثبت کنید: با بدنه JSON {"certificateFingerprintSha256": "..."} با POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys (CreateAndroidPackageKey) تماس بگیرید. وضعیت برگردانده‌شده را بررسی کنید:
   • DRAFT: اثبات مالکیت کلید خصوصی الزامی است و پاسخ شامل یک verificationToken منحصربه‌فرد برای مرحله ۷ است.
   • IN_REVIEW: اثبات مالکیت و توجیه به‌طور خودکار رد می‌شود (برای مثال، هنگام ثبت نام بسته جدیدی که هرگز در Android دیده نشده است، یا وقتی قبلاً مالکیت این کلید امضا را برای نام بسته دیگری در همان DeveloperAccount درستی‌سنجی کرده‌اید). مرحله ۷ و فراخوانی توجیه در مرحله ۸ را رد کنید و مستقیماً به نظرسنجی GetAndroidPackage و GetAndroidPackageKey بروید.
7. فایل APK درستی‌سنجی را بسازید و بارگذاری کنید (اگر وضعیت DRAFT است): رشته verificationToken برگردانده‌شده را در assets/adi-registration.properties داخل یک فایل APK حداقلی مطابق با packageName جاسازی کنید، آن را با کلید خصوصی امضای برنامه‌تان امضا کنید، و آن را بااستفاده از POST /upload/v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:verify (VerifyAndroidPackageKeyOwnership) بارگذاری کنید.
8. ارسال توجیه (درصورت نیاز) و وضعیت ثبت نظرسنجی: اگر کلید در وضعیت OWNERSHIP_VERIFIED و registrationJustificationRequired true است، با POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:justifyAndroidPackageKeyRegistration (JustifyAndroidPackageKeyRegistration) تماس بگیرید. نظرسنجی GetAndroidPackage و GetAndroidPackageKey تا زمانی که state به REGISTERED برسد.

فرمان‌های CLI محلی برای آماده‌سازی اثر انگشت کلید و APK درستی‌سنجی

• استخراج اثر انگشت گواهینامه SHA-256 از keystore (keytool):

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

• درستی‌سنجی کردن خلاصه گواهی امضای SHA-256 در APK ساخته‌شده (apksigner):

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

• بررسی نام بسته APK و فایل کد جاسازی‌شده قبل‌از بارگذاری (aapt2 و unzip):

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

قابلیت‌های میانای برنامه‌سازی کاربردی و واسط کاربر Android Developer Console

پیکربندی و اصالت‌سنجی سرویس

همه درخواست‌های میانای برنامه‌سازی کاربردی باید از HTTPS استفاده کنند و شامل سرصفحه Authorization: Bearer ACCESS_TOKEN باشند که بااستفاده از جریان سرور وب OAuth 2.0 برای «حساب Google» که درستی‌سنجی هویت توسعه‌دهنده را در کنسول توسعه‌دهنده Android تکمیل کرده است به‌دست آمده باشد.

منابع و نقاط پایان API

Android Developer Console API منابع را در سلسله‌مراتب زیر سازمان‌دهی می‌کند:

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

منبع: DeveloperAccount

نشان‌دهنده حسابی در Android Developer Console است که با هویت توسعه‌دهنده مرتبط است.

Enum: DeveloperAccount.VerificationState

روش‌ها: DeveloperAccount

منبع: AndroidPackage

نشان‌دهنده نام بسته Android است که تحت DeveloperAccount ثبت شده است یا درحال ثبت شدن است.

Enum: AndroidPackage.State

منبع: AndroidPackageRegistrationPolicy

منبع تک‌عضوی برگردانده‌شده توسط GetAndroidPackageRegistrationPolicy که کلیدهای امضای عمومی قدیمی شناسایی‌شده برای نام بسته را شرح می‌دهد و اینکه آیا ثبت نام بسته با کلید امضای داده‌شده به توجیه کتبی نیاز دارد یا نه.

Enum: KnownKey.JustificationRequirement

Enum: AndroidPackageRegistrationPolicy.KeySelectionStrategy

روش‌ها: AndroidPackage

منبع: AndroidPackageKey

نشان‌دهنده اثر انگشت گواهی امضای برنامه عمومی منسوب به AndroidPackage است و وضعیت بازبینی ثبت و درستی‌سنجی مالکیت را ردیابی می‌کند.

Enum: AndroidPackageKey.State

روش‌ها: AndroidPackageKey

مدیریت کردن خطا

وقتی درخواست API ناموفق باشد، Android Developer Console API رمز وضعیت HTTP 4xx یا 5xx و بدنه خطای JSON استاندارد google.rpc.Status را برمی‌گرداند:

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

رمزهای وضعیت HTTP و راه‌حل‌های رایج

نمونه‌های درخواست و پاسخ اچ‌تی‌تی‌پی

مقادیر جای‌بان مثل ACCESS_TOKEN، 1234567890، com.example.myapp، و 60e860e8... را با مقادیر خودتان جایگزین کنید.

۱. GetDeveloperAccount

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

پاسخ:

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

۲. ListDeveloperAccounts

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

پاسخ:

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

۳. GetAndroidPackageRegistrationPolicy

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

پاسخ:

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

۴. 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"

پاسخ:

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

۵. GetAndroidPackage

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

پاسخ:

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

۶. ListAndroidPackages

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

پاسخ:

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

‫۷. 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"

پاسخ:

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

‫۸. GetAndroidPackageKey

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

پاسخ:

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

‫۹. ListAndroidPackageKeys

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

پاسخ:

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

‫۱۰. VerifyAndroidPackageKeyOwnership

گزینه الف: بارگذاری رسانه با درخواست واحد

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"

گزینه ب: پروتکل بارگذاری ازسرگرفتنی (برای فایل‌های APK بزرگ یا CI/CD توصیه می‌شود)

مرحله ۱: جلسه بارگذاری ازسرگرفتنی را شروع کنید و سرصفحه 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"
  }'

مرحله ۲: فایل دودویی APK امضاشده را در UPLOAD_SESSION_URI بارگذاری کنید و جلسه را نهایی کنید:

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"

پاسخ:

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

‫۱۱. 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"

پاسخ:

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

منابع بیشتر

• ثبت کردن نام بسته‌ها با Android Developer Console API
• بررسی وضعیت ثبت برنامه با Android Developer ID Status API
• ثبت‌نام در Android Developer Console
• ثبت‌نام در «کنسول Google Play»