وضعیت ثبت برنامه را با API وضعیت شناسه توسعه‌دهنده اندروید بررسی کنید

از API وضعیت توسعه‌دهنده اندروید (Android Developer Status API) برای بررسی اینکه آیا نام بسته برنامه اندروید به یک توسعه‌دهنده تأیید شده ثبت شده است یا خیر، استفاده کنید. اگر ابزارهای توسعه نرم‌افزار، IDEها یا گردش‌های کاری خودکار CI/CD می‌سازید، می‌توانید این API سرور به سرور را برای انجام موارد زیر ادغام کنید:

• بررسی کنید که آیا نام بسته برنامه به نام یک توسعه‌دهنده تأیید شده ثبت شده است یا خیر
• اعتبارسنجی اینکه آیا گواهی امضای برنامه با اثر انگشت SHA-256 با اعتبارنامه‌های موجود در فایل مربوط به نام بسته ثبت‌شده مطابقت دارد یا خیر
• از توسعه‌دهندگان در رابط کاربری ابزار خود بخواهید برنامه‌های ناشناخته را در برنامه تأیید توسعه‌دهندگان اندروید ثبت کنند.

این API برای پشتیبانی از گردش‌های کاری مختلف توسعه‌دهندگان طراحی شده است:

مورد استفاده	توضیحات	نقطه پایانی API
واجد شرایط بودن نام بسته	بررسی می‌کند که آیا نام یک بسته قبلاً ثبت شده است یا خیر. اگر نام بسته به هر توسعه‌دهنده‌ی تأیید شده‌ای لینک شده باشد، مقدار REGISTERED را برمی‌گرداند، در غیر این صورت NOT_REGISTERED برمی‌گرداند.	CheckPackageRegistrationStatus
برنامه ثبت شده است	بررسی اینکه آیا یک جفت اثر انگشت نام بسته و گواهی خاص ثبت شده است یا خیر. اگر جفت اثر انگشت نام بسته و گواهی ثبت شده باشد، مقدار REGISTERED برمی‌گرداند، اگر جفت اثر انگشت نام بسته و گواهی ثبت نشده باشد، NOT_REGISTERED برمی‌گرداند، یا اگر نام بسته با اثر انگشت گواهی متفاوتی ثبت شده باشد، REGISTERED_WITH_ANOTHER_CERTIFICATE_FINGERPRINT برمی‌گرداند.	CheckPackageRegistrationStatus

این راهنما نحوه انجام وظایف زیر را توضیح می‌دهد:

1. دسترسی و احراز هویت Google Cloud API را تنظیم کنید.
2. بررسی کنید که آیا نام بسته برنامه و جفت اثر انگشت SHA-256 گواهی عمومی توسط یک توسعه‌دهنده تأیید شده، یا با اثر انگشت SHA-256 گواهی عمومی ارائه شده یا با اثر انگشت SHA-256 گواهی عمومی متفاوت، در برنامه تأیید توسعه‌دهنده اندروید ثبت شده‌اند یا خیر.
3. مدیریت وضعیت‌های ثبت API در IDE یا گردش کار ابزار توسعه‌دهنده شما.

پیش‌نیازها

این سند برای توسعه‌دهندگان برنامه‌های اندروید یا توسعه‌دهندگان ابزارهای توسعه نرم‌افزار در نظر گرفته شده است. قبل از شروع، باید موارد زیر را داشته باشید:

• دسترسی مدیریتی به یک پروژه Google Cloud.
• درک اولیه از APIهای RESTful، JSON و اثر انگشت‌های گواهی SHA-256.

همچنین باید با اصطلاحات زیر آشنا باشید:

مدت	تعریف
تأیید توسعه‌دهنده اندروید	تأیید توسعه‌دهنده اندروید یک الزام جدید است که برای پیوند دادن نهادهای دنیای واقعی (افراد و سازمان‌ها) با برنامه‌های اندروید آنها طراحی شده است. اندروید از این پس ملزم می‌کند که همه برنامه‌ها توسط توسعه‌دهندگان تأیید شده ثبت شوند تا توسط کاربران روی دستگاه‌های اندروید دارای مجوز نصب شوند.
اثر انگشت گواهینامه	هش SHA-256 گواهی عمومی مورد استفاده برای امضای برنامه.
ایالت ثبت نام	وضعیتی که توسط API برای نام بسته یک برنامه یا جفت اثر انگشت SHA-256 نام بسته و گواهی عمومی یک برنامه برگردانده می‌شود. این وضعیت، عملی را که باید انجام دهید، دیکته می‌کند (برای مثال، REGISTERED ، NOT_REGISTERED ).

نقطه پایانی سرویس

یک نقطه پایانی سرویس ، یک URL پایه است که آدرس شبکه یک سرویس API را مشخص می‌کند. این سرویس دارای نقطه پایانی سرویس زیر است و همه URI ها نسبت به این نقطه پایانی سرویس هستند:

https://androiddeveloperidstatus.googleapis.com

فعال کردن API

برای استفاده از API وضعیت شناسه توسعه‌دهنده اندروید، باید مراحل راه‌اندازی را برای ایجاد یک پروژه و فعال کردن API انجام دهید.

ایجاد یک پروژه گوگل کلود

1. اگر حساب گوگل کلود ندارید، یک حساب ایجاد کنید.
2. کنسول گوگل کلود را باز کنید.
3. یک پروژه گوگل کلود ایجاد کنید.

فعال کردن API در پروژه شما

1. در کنسول گوگل کلود، به APIها و خدمات > کتابخانه بروید.
2. پروژه خود را از منوی کشویی انتخاب کنید.
3. عبارت «Android Developer ID Status API» را جستجو کنید.
4. روی فعال کردن کلیک کنید.

احراز هویت

این API از اعتبارنامه‌های کلید API پشتیبانی می‌کند. برای دریافت کلید API:

1. در کنسول گوگل کلود، به APIها و خدمات > اعتبارنامه‌ها بروید.
2. روی + ایجاد اعتبارنامه کلیک کنید و کلید API را انتخاب کنید.
3. کلید را پیکربندی و کپی کنید. از این کلید در هدرهای درخواست خود استفاده کنید.

بررسی وضعیت ثبت برنامه

شما می‌توانید از منبع PackageRegistrationStatus برای تأیید نام بسته به تنهایی یا بررسی نام بسته همراه با یک اثر انگشت گواهی خاص، پرس و جو کنید.

نام بسته را بررسی کنید

برای بررسی اینکه آیا نام بسته‌ی برنامه توسط توسعه‌دهنده‌ی تأییدشده‌ای ثبت شده است یا خیر، یک درخواست GET احراز هویت‌شده حاوی نام بسته‌ی برنامه‌ی اندروید (برای مثال، com.example.app ) را به نقطه‌ی پایانی packageRegistrationStatus:check بدون پارامترهای اختیاری ارسال کنید:

درخواست:

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

نتایج

پاسخ (ثبت‌شده):

اگر نام بسته ثبت شده باشد، بدنه پاسخ HTTP زیر را با کد پاسخ HTTP 200 دریافت خواهید کرد:

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

اقدام پیشنهادی: به توسعه‌دهنده اطلاع دهید که نام بسته قبلاً ثبت شده است.

پاسخ (ثبت نشده):

اگر نام بسته ثبت نشده باشد، بدنه پاسخ HTTP زیر را با کد پاسخ HTTP 200 دریافت خواهید کرد:

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

تأیید جفت اثر انگشت نام بسته و گواهی

برای بررسی اینکه آیا نام بسته برنامه با یک اثر انگشت SHA-256 گواهی عمومی خاص ثبت شده است یا خیر، پارامتر پرس و جوی certificateFingerprint را ارسال کنید:

درخواست:

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

نتایج

پاسخ (ثبت شده با اثر انگشت گواهی تطبیق):

اگر نام بسته با گواهی عمومی ارائه شده با اثر انگشت SHA-256 ثبت شده باشد، بدنه پاسخ HTTP زیر را با کد پاسخ HTTP 200 دریافت خواهید کرد:

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

پاسخ (با اثر انگشت گواهی متفاوت ثبت شده است):

اگر نام بسته با گواهی اثر انگشت SHA-256 متفاوتی نسبت به آنچه ارائه شده است ثبت شده باشد، بدنه پاسخ HTTP زیر را با کد پاسخ HTTP 200 دریافت خواهید کرد:

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

پاسخ (ثبت نشده):

اگر نام بسته با گواهی عمومی ارائه شده، اثر انگشت SHA-256 ثبت نشده باشد، بدنه پاسخ HTTP زیر را با کد پاسخ HTTP 200 دریافت خواهید کرد:

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

مثال پیاده‌سازی جاوا

کلاس جاوای زیر نحوه فراخوانی API را با استفاده از HttpClient استاندارد جاوا ۱۱ نشان می‌دهد.

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();
  }
}

درک وضعیت‌های ثبت و مدیریت خطا

وقتی یک درخواست API با شکست مواجه می‌شود، API وضعیت شناسه توسعه‌دهنده اندروید (Android Developer ID Status API) یک شیء خطای استاندارد Google Cloud JSON را در بدنه پاسخ برمی‌گرداند. این شیء یک ساختار منسجم برای درک و مدیریت خطا فراهم می‌کند.

پاسخ خطای نمونه:

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

شیء خطا شامل فیلدهای کلیدی زیر است:

• code : کد وضعیت HTTP (برای مثال، 400 ، 403 ، 500 ).
• message : توضیحی انگلیسی از خطا که برای توسعه‌دهندگان قابل فهم است. این پیام پایدار نیست و می‌تواند تغییر کند، بنابراین منطق تجزیه را بر اساس آن ایجاد نکنید.
• status : یک کد خطای متعارف که به صورت برنامه‌نویسی شده نوع خطا را مشخص می‌کند (برای مثال، INVALID_ARGUMENT ، PERMISSION_DENIED ). منطق مدیریت خطای شما باید بر اساس این شناسه پایدار ساخته شود.

جدول زیر رایج‌ترین خطاهایی که توسط API برگردانده می‌شوند و اقدامات پیشنهادی برای رفع آنها را فهرست می‌کند.

وضعیت HTTP	کد خطای متعارف ( status )	معنا و علت مشترک	اقدام توصیه شده	میشه دوباره امتحان داد؟
درخواست بد 400	INVALID_ARGUMENT	درخواست ناقص بود.	دوباره امتحان نکنید. فیلد جزئیات را در پاسخ خطا بررسی کنید تا تخلف فیلد خاص را شناسایی کنید. بار داده درخواست را اصلاح کنید و دوباره آن را ارسال کنید.	خیر
401 غیرمجاز	UNAUTHENTICATED	توکن دسترسی وجود ندارد، منقضی شده یا نامعتبر است.	فوراً دوباره امتحان نکنید. مطمئن شوید که از توکن یا کلید دسترسی صحیح استفاده می‌کنید.	خیر
403 ممنوعه	PERMISSION_DENIED	شما احراز هویت شده‌اید، اما پروژه شما اجازه دسترسی به API را ندارد. شایع‌ترین علت این است که API را در پروژه Google Cloud خود فعال نکرده‌اید.	دوباره امتحان نکنید. تأیید کنید که از شناسه پروژه صحیح استفاده می‌کنید و API فعال است.	خیر
429 درخواست‌های بیش از حد	RESOURCE_EXHAUSTED	شما از سهمیه API برای پروژه خود فراتر رفته‌اید.	ارسال درخواست‌ها را متوقف کنید و پس از یک تأخیر دوباره امتحان کنید. سهمیه‌های پروژه خود را در کنسول Google Cloud بررسی کنید.	بله
خطای داخلی سرور 500	INTERNAL	خطای غیرمنتظره‌ای در سرورهای گوگل رخ داد.	این احتمالاً یک مشکل گذرا است. درخواست را با استفاده از استراتژی backoff نمایی دوباره امتحان کنید. اگر خطا ادامه داشت، با پشتیبانی تماس بگیرید.	بله
سرویس 503 در دسترس نیست	UNAVAILABLE	سرویس موقتاً در دسترس نیست.	درخواست را با استفاده از یک استراتژی backoff نمایی دوباره امتحان کنید.	بله

محدودیت‌های سهمیه

سهمیه‌های استفاده بر اساس هر پروژه اعمال می‌شوند تا از قابلیت اطمینان سرویس اطمینان حاصل شود.

روش API	محدودیت پیش‌فرض (به ازای هر پروژه)	یادداشت‌ها
CheckPackageRegistrationStatus	۱۰۰۰ درخواست در روز	تماس‌گیرندگان موظفند برای جلوگیری از سوءاستفاده، محدودیت نرخ داخلی را مدیریت کنند.

میزان استفاده خود را زیر نظر داشته باشید

شما می‌توانید میزان استفاده فعلی از API پروژه خود را رصد کنید و ببینید که چقدر به محدودیت‌های سهمیه خود نزدیک شده‌اید، مستقیماً در کنسول Google Cloud.

1. به صفحه APIها و خدمات > داشبورد بروید.
2. API وضعیت شناسه توسعه‌دهنده اندروید را انتخاب کنید.
3. روی برگه سهمیه‌ها کلیک کنید.

این داشبورد، جزئیات دقیقی از حجم درخواست‌های شما را در طول زمان ارائه می‌دهد.