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 واحصل على رمز مميّز للوصول إلى Bearer OAuth 2.0 مفوَّض من المستخدم مع النطاق 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: يمكنك طلب POST /v1/developerAccounts/{id}/androidPackages?androidPackageId={pkg} (CreateAndroidPackage) مع النص {"name": ""} (يتم إنشاء المورد في الحالة DRAFT).
6. تسجيل الملف المرجعي لمفتاح توقيع التطبيق: يمكنك طلب POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys (CreateAndroidPackageKey) باستخدام نص JSON‏ {"certificateFingerprintSha256": "..."}. افحص الحالة التي تم إرجاعها:
   • ‫DRAFT: يجب تقديم إثبات ملكية المفتاح الخاص، ويتضمّن الردّ verificationToken فريدًا للخطوة 7.
   • ‫IN_REVIEW: يتم تخطّي إثبات الملكية والمبرّر تلقائيًا (على سبيل المثال، عند تسجيل اسم حزمة جديد لم يسبق استخدامه على Android، أو عند إثبات ملكية مفتاح التوقيع هذا لاسم حزمة آخر في DeveloperAccount نفسه). تخطَّ الخطوة 7 وطلب المبرّر في الخطوة 8، وانتقِل مباشرةً إلى استطلاع 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 من ملف تخزين مفاتيح (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 Developer Console.

موارد واجهة برمجة التطبيقات ونقاط النهاية

تُنظّم واجهة برمجة التطبيقات 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 مرتبطًا بهوية مطوّر.

قيم التعداد: DeveloperAccount.VerificationState

الطرق: DeveloperAccount

المورد: AndroidPackage

يمثّل اسم حزمة Android المسجَّل أو الذي يتم تسجيله ضمن DeveloperAccount.

Enum: AndroidPackage.State

المورد: AndroidPackageRegistrationPolicy

مورد Singleton الذي يعرضه GetAndroidPackageRegistrationPolicy ويصف مفاتيح التوقيع العلنية السابقة التي تم رصدها لاسم حزمة وما إذا كان تسجيل اسم الحزمة باستخدام مفتاح توقيع معيّن يتطلّب تقديم سبب مكتوب.

Enum: KnownKey.JustificationRequirement

Enum: AndroidPackageRegistrationPolicy.KeySelectionStrategy

الطرق: AndroidPackage

المورد: AndroidPackageKey

تمثّل هذه السمة الملف المرجعي لشهادة توقيع التطبيق المتاحة للجميع والمرتبطة بـ AndroidPackage وتتتبّع حالة إثبات الملكية ومراجعة التسجيل.

Enum: AndroidPackageKey.State

الطرق: AndroidPackageKey

معالجة الأخطاء

عند تعذُّر طلب بيانات من واجهة برمجة التطبيقات، تعرض واجهة برمجة تطبيقات Android Developer Console رمز حالة HTTP 4xx أو 5xx ونص خطأ JSON google.rpc.Status عادي:

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

رموز حالة HTTP والحلول الشائعة

أمثلة على طلبات واستجابات HTTP

استبدِل قيم العناصر النائبة، مثل ACCESS_TOKEN و1234567890 وcom.example.myapp و60e860e8...، بقيمك الخاصة.

1. GetDeveloperAccount

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

الردّ:

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

2. ListDeveloperAccounts

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

الردّ:

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

الردّ:

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

الردّ:

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

الردّ:

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

الردّ:

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

الردّ:

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

الردّ:

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

الردّ:

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

10. 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)

الخطوة 1: ابدأ جلسة التحميل القابل للاستئناف واستخرِج العنوان 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"
  }'

الخطوة 2: تحميل ملف 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"
}

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"

الردّ:

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