Android 개발자 ID 상태 API로 앱 등록 상태 확인

Android Developer Status API를 사용하여 Android 앱 패키지 이름이 인증된 개발자에게 등록되었는지 확인합니다. 소프트웨어 개발 도구, IDE 또는 자동화된 CI/CD 워크플로를 빌드하는 경우 이 서버 간 API를 통합하여 다음 작업을 실행할 수 있습니다.

  • 앱 패키지 이름이 인증된 개발자에게 등록되었는지 확인합니다.
  • 앱의 서명 인증서 SHA-256 지문이 등록된 패키지 이름의 파일에 있는 사용자 인증 정보와 일치하는지 확인합니다.
  • 도구의 인터페이스 내에서 개발자에게 Android 개발자 인증 프로그램에 인식되지 않는 앱을 등록하라는 메시지를 표시합니다.

이 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 지문 쌍을 Android 개발자 인증 프로그램에 등록했는지 확인합니다.
  3. IDE 또는 개발자 도구 워크플로에서 API 등록 상태를 처리합니다.

기본 요건

이 문서는 Android 앱 개발자 또는 소프트웨어 개발 도구 개발자를 대상으로 합니다. 시작하기 전에 다음이 있어야 합니다.

  • Google Cloud 프로젝트에 대한 관리 액세스 권한
  • RESTful API, JSON, SHA-256 인증서 지문에 대한 기본적인 이해

다음 용어도 알고 있어야 합니다.

용어 정의
Android 개발자 인증 Android 개발자 인증은 실제 법인 (개인 및 조직)을 Android 앱과 연결하도록 설계된 새로운 요구사항입니다. Android에서는 사용자가 인증된 Android 기기에 앱을 설치하려면 인증된 개발자가 모든 앱을 등록해야 합니다.
인증서 지문 앱에 서명하는 데 사용되는 공개 인증서의 SHA-256 해시입니다.
등록 상태 앱의 패키지 이름 또는 앱의 패키지 이름과 공개 인증서 SHA-256 지문 쌍에 대해 API에서 반환하는 상태입니다. 이 상태는 취해야 하는 작업을 결정합니다 (예: REGISTERED, NOT_REGISTERED).

서비스 엔드포인트

서비스 엔드포인트는 API 서비스의 네트워크 주소를 지정하는 기준 URL입니다. 이 서비스에는 다음 서비스 엔드포인트가 포함되고 모든 URI가 이 서비스 엔드포인트를 기준으로 합니다.

https://androiddeveloperidstatus.googleapis.com

API 사용 설정

Android Developer ID Status API를 사용하려면 설정 단계를 완료하여 프로젝트를 만들고 API를 사용 설정해야 합니다.

Google Cloud 프로젝트 만들기

  1. Google Cloud 계정이 없으면 계정을 만듭니다.
  2. Google Cloud 콘솔을 엽니다.
  3. Google Cloud 프로젝트를 만듭니다.

프로젝트에서 API 사용 설정

  1. Google Cloud 콘솔에서 API 및 서비스 > 라이브러리 로 이동합니다.
  2. 드롭다운 메뉴에서 프로젝트를 선택합니다.
  3. Android Developer ID Status API 를 검색합니다.
  4. 사용 설정 을 클릭합니다.

인증

API는 API 키 사용자 인증 정보를 지원합니다. API 키를 가져오려면 다음 안내를 따르세요.

  1. Google Cloud 콘솔에서 API 및 서비스 > 사용자 인증 정보 로 이동합니다.
  2. + 사용자 인증 정보 만들기 를 클릭하고 API 키 를 선택합니다.
  3. 키를 구성하고 복사합니다. 요청 헤더에서 이 키를 사용합니다.

앱 등록 상태 확인

PackageRegistrationStatus 리소스를 쿼리하여 패키지 이름만 확인하거나 특정 인증서 지문과 페어링된 패키지 이름을 확인할 수 있습니다.

패키지 이름 확인

앱 패키지 이름이 인증된 개발자에 의해 등록되었는지 확인하려면 선택적 매개변수 없이 Android 앱의 패키지 이름 (예: com.example.app)이 포함된 인증된 GET 요청을 packageRegistrationStatus:check 엔드포인트로 전송합니다.

요청:

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

결과

응답 (등록됨):

패키지 이름이 등록된 경우 HTTP 응답 코드 200과 함께 다음 HTTP 응답 본문이 수신됩니다.

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

권장 조치: 개발자에게 패키지 이름이 이미 등록되어 있다고 알립니다.

응답 (등록되지 않음):

패키지 이름이 등록되지 않은 경우 HTTP 응답 코드 200과 함께 다음 HTTP 응답 본문이 수신됩니다.

{
  "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 응답 코드 200과 함께 다음 HTTP 응답 본문이 수신됩니다.

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

응답 (다른 인증서 지문으로 등록됨):

패키지 이름이 제공된 인증서 SHA-256 지문과 다른 인증서 SHA-256 지문으로 등록된 경우 HTTP 응답 코드 200과 함께 다음 HTTP 응답 본문이 수신됩니다.

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

응답 (등록되지 않음):

패키지 이름이 제공된 공개 인증서 SHA-256 지문으로 등록되지 않은 경우 HTTP 응답 코드 200과 함께 다음 HTTP 응답 본문이 수신됩니다.

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

Java 구현 예

다음 Java 클래스는 Java 11의 표준 HttpClient를 사용하여 API를 호출하는 방법을 보여줍니다.

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 요청이 실패하면 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에 액세스할 권한이 없습니다. 가장 일반적인 원인은 Google Cloud 프로젝트에서 API를 사용 설정하지 않은 것입니다. 재시도하지 마세요. 올바른 프로젝트 ID를 사용하고 있고 API가 사용 설정되어 있는지 확인합니다. 아니요
429 요청한 횟수가 너무 많음 RESOURCE_EXHAUSTED 프로젝트의 API 할당량을 초과했습니다. 요청 전송을 중지하고 지연 후 다시 시도합니다. Google Cloud 콘솔에서 프로젝트의 할당량을 확인합니다.
500 내부 서버 오류 INTERNAL Google 서버에서 예기치 않은 오류가 발생했습니다. 일시적인 문제일 수 있습니다. 지수 백오프 전략을 사용하여 요청을 다시 시도합니다. 오류가 계속되면 지원팀에 문의하세요.
503 서비스를 사용할 수 없음 UNAVAILABLE 서비스를 일시적으로 사용할 수 없습니다. 지수 백오프 전략을 사용하여 요청을 다시 시도합니다.

할당량 한도

서비스 안정성을 보장하기 위해 사용 할당량은 프로젝트별로 적용됩니다.

API 메서드 기본 한도 (프로젝트당) 참고
CheckPackageRegistrationStatus 요청 1,000개/일 호출자는 악용을 방지하기 위해 내부 속도 제한을 관리해야 합니다.

사용량 모니터링

Google Cloud 콘솔에서 프로젝트의 현재 API 사용량을 모니터링하고 할당량 한도에 얼마나 가까워졌는지 직접 확인할 수 있습니다.

  1. API 및 서비스 > 대시보드 페이지로 이동합니다.
  2. Android Developer ID Status API를 선택합니다.
  3. 할당량 탭을 클릭합니다.

이 대시보드는 시간 경과에 따른 요청 볼륨의 세부 분석을 제공합니다.