API 키 사용하기

여기에서는 Android용 Maps SDK에 사용할 API 키를 만들어 앱에 추가하고 키를 제한하여 앱을 보호하는 방법을 설명합니다. SDK를 사용하는 앱에는 반드시 API 키를 추가해야 합니다.

시작하기 전에

Android용 Maps SDK를 사용하려면 결제 계정이 있고 Android용 Maps SDK가 사용 설정된 프로젝트가 필요합니다. 자세한 내용은 Cloud Console에서 설정하기를 참고하세요.

API 키 만들기

API 키는 사용 및 결제에 관한 프로젝트와 관련된 요청을 인증하는 고유 식별자입니다. 프로젝트에 연결된 API 키가 하나 이상 있어야 합니다.

API 키를 만들려면 다음 단계를 따르세요.

콘솔

  1. Google Maps Platform > 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보 페이지로 이동하기

  2. 사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 > API 키를 클릭합니다.
    API 키 생성 완료 대화상자에 새로 만든 API 키가 표시됩니다.
  3. 닫기를 클릭합니다.
    새 API 키는 사용자 인증 정보 페이지의 API 키 아래 나열됩니다.
    (프로덕션에 사용하기 전에 API 키를 제한하세요.)

Cloud SDK

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Google Cloud SDK, Cloud SDK 설치 및 다음 명령어에 대해 자세히 알아보세요.

앱에 API 키 추가

이 섹션에서는 앱에서 더욱 안전하게 참조할 수 있도록 API 키를 저장하는 방법에 대해서 설명합니다. API 키는 버전 제어 시스템에 등록하면 안 되며, 프로젝트의 루트 디렉터리에 있는 local.properties 파일에 저장하는 것이 좋습니다. local.properties 파일에 관한 자세한 내용은 Gradle 속성 파일을 참고하세요.

이 작업을 간단히 진행하고 싶다면 Android용 Secrets Gradle Plugin을 사용하세요.

플러그인을 설치하여 API 키를 저장하는 방법은 다음과 같습니다.

  1. Android 스튜디오에서 루트 수준 build.gradle 파일을 열고 다음 코드를 buildscript 아래 dependencies 요소에 추가합니다.
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
        }
    }
        
  2. 그런 다음 앱 수준 build.gradle 파일을 열고 plugins 요소에 다음 코드를 추가합니다.
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. 파일을 저장하고 프로젝트를 Gradle과 동기화합니다.
  4. 프로젝트 수준 디렉터리에서 local.properties를 열고 다음 코드를 추가합니다. YOUR_API_KEY를 API 키로 변경합니다.
    MAPS_API_KEY=YOUR_API_KEY
        
  5. 파일을 저장하고 프로젝트를 Gradle과 동기화합니다.
  6. AndroidManifest.xml 파일에서 com.google.android.geo.API_KEY로 이동한 후 android:value attribute를 다음과 같이 업데이트합니다.
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

참고: 위의 내용처럼, com.google.android.geo.API_KEY는 API 키의 권장 메타데이터 이름입니다. 이 이름의 키는 Android 플랫폼에서 Android용 Maps SDK 등 여러 Google 지도 기반 API를 인증하는 데 사용할 수 있습니다. 이전 버전과의 호환성을 위해 API에서는 com.google.android.maps.v2.API_KEY 이름도 지원합니다. 이 기존 이름을 사용하면 Android 지도 API v2만 인증할 수 있습니다. 애플리케이션에서는 API 키 메타데이터 이름을 하나만 지정할 수 있습니다. 두 개가 모두 지정되면 API에서 예외가 발생합니다.

API 키 제한

API 키를 제한하면 승인된 요청만 API 키로 실행되기 때문에 애플리케이션 보안이 강화됩니다. 안내에 따라 API 키에 대한 제한을 설정하시기 바랍니다. 자세한 내용은 API 키 권장사항을 참고하세요.

API 키를 제한하는 경우 애플리케이션에 서명하는 데 사용된 서명 키의 SHA-1 인증서 디지털 지문을 제공해야 합니다. 다음과 같은 두 가지 인증서 유형이 있습니다.

  • 디버그 인증서: 테스트 중인 앱 및 기타 비프로덕션 코드에서만 이 인증서 유형을 사용합니다. 디버그 인증서로 서명된 앱은 게시하지 마세요. Android SDK 도구는 디버그 빌드 실행 시 이 인증서를 자동으로 생성합니다.
  • 출시 인증서: 앱을 앱 스토어에 출시할 준비가 되면 이 인증서를 사용합니다. Android SDK 도구는 출시 빌드 실행 시 이 인증서를 생성합니다.

디지털 인증서에 대한 자세한 내용은 앱 서명 관련 가이드를 참고하세요.

인증서 디지털 지문 가져오기에 대한 자세한 내용은 클라이언트 인증을 참조하세요. 대신 Play 앱 서명을 사용 중이라면 Play Console에서 앱 서명 페이지로 이동해 인증서 디지털 지문을 가져와야 합니다.

API 키를 제한하는 방법은 다음과 같습니다.

콘솔

  1. Google Maps Platform > 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보 페이지로 이동하기

  2. 제한을 설정할 API 키를 선택합니다. API 키 속성 페이지가 나타납니다.
  3. 키 제한사항에서 다음 제한사항을 설정합니다.
    • 애플리케이션 제한:
      1. Android 앱을 선택합니다.
      2. + 패키지 이름 및 디지털 지문 추가를 클릭합니다.
      3. 패키지 이름과 SHA-1 인증서 디지털 지문을 입력합니다. 예를 들면 다음과 같습니다.
        com.example.android.mapexample
        BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
    • API 제한:
      1. 키 제한을 클릭합니다.
      2. API 선택 드롭다운에서 Android용 Maps SDK를 선택합니다. Android용 Maps SDK가 표시되지 않으면 사용 설정해야 합니다.
  4. 변경을 완료하려면 저장을 클릭합니다.

Cloud SDK

기존 키를 나열합니다.

gcloud services api-keys list --project="PROJECT"

기존 키에 대한 기존 제한을 삭제합니다.

gcloud alpha services api-keys update "projects/PROJECT/keys/KEY_ID" \
    --clear-restrictions

기존 키에 새로운 제한을 설정합니다.

gcloud alpha services api-keys update "projects/PROJECT/keys/KEY_ID" \
    --api_target="maps-android-backend.googleapis.com"
    --allowed-application="sha1_fingerprint=SHA1_FINGERPRINT,package_name=ANDROID_PACKAGE_NAME"

Google Cloud SDK, Cloud SDK 설치 및 다음 명령어에 대해 자세히 알아보세요.