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

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

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

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

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

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

پیش‌نیازها

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

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

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

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

یک نقطه پایانی سرویس ، یک 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 برگردانده می‌شوند و اقدامات پیشنهادی برای رفع آنها را فهرست می‌کند.

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

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

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

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

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

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