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 |
이 가이드에서는 다음 작업을 완료하는 방법을 설명합니다.
- Google Cloud API 액세스 및 인증을 설정합니다.
- 제공된 공개 인증서 SHA-256 지문 또는 다른 공개 인증서 SHA-256 지문을 사용하여 인증된 개발자가 앱의 패키지 이름과 공개 인증서 SHA-256 지문 쌍을 Android 개발자 인증 프로그램에 등록했는지 확인합니다.
- 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 프로젝트 만들기
- Google Cloud 계정이 없으면 계정을 만듭니다.
- Google Cloud 콘솔을 엽니다.
- Google Cloud 프로젝트를 만듭니다.
프로젝트에서 API 사용 설정
- Google Cloud 콘솔에서 API 및 서비스 > 라이브러리 로 이동합니다.
- 드롭다운 메뉴에서 프로젝트를 선택합니다.
- Android Developer ID Status API 를 검색합니다.
- 사용 설정 을 클릭합니다.
인증
API는 API 키 사용자 인증 정보를 지원합니다. API 키를 가져오려면 다음 안내를 따르세요.
- Google Cloud 콘솔에서 API 및 서비스 > 사용자 인증 정보 로 이동합니다.
- + 사용자 인증 정보 만들기 를 클릭하고 API 키 를 선택합니다.
- 키를 구성하고 복사합니다. 요청 헤더에서 이 키를 사용합니다.
앱 등록 상태 확인
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 사용량을 모니터링하고 할당량 한도에 얼마나 가까워졌는지 직접 확인할 수 있습니다.
- API 및 서비스 > 대시보드 페이지로 이동합니다.
- Android Developer ID Status API를 선택합니다.
- 할당량 탭을 클릭합니다.
이 대시보드는 시간 경과에 따른 요청 볼륨의 세부 분석을 제공합니다.