API 키 사용

이 문서에서는 애플리케이션 개발자가 Google Cloud APIs에서 API 키를 사용하는 방법을 보여줍니다. API 키는 주 구성원 없이 애플리케이션을 식별하는 간단한 암호화된 문자열입니다. 익명으로 공개 데이터에 액세스하는 데 유용하며 할당량 및 결제를 위해 API 요청을 프로젝트와 연결하는 데 사용됩니다.

Google Cloud APIs 인증에 대한 자세한 내용과 일반적인 시나리오에 가장 적합한 인증 전략을 확인하려면 인증 개요를 참조하세요. Google Maps Platform API 및 SDK에 API 키를 사용하는 방법을 자세히 알아보려면 Google Maps Platform 문서를 참조하세요.

직접 사용해 보기

Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

무료로 시작하기

API 키 관리

Cloud Console을 사용하여 API 키를 관리하는 것이 좋습니다. Cloud Console에서 API 및 서비스 → 사용자 인증 정보 페이지로 이동합니다. API 키는 API 키 섹션에 표시됩니다. 이 페이지에서 API 키를 만들고, API 키 제한사항을 정의하고, API 키 문자열을 순환시키고, 기타 작업을 수행할 수 있습니다.

API 키 만들기

프로젝트에서 API 키를 만들려면 사용자에게 프로젝트에 대한 편집자 기본 역할(roles/editor)을 부여해야 합니다. 자세한 내용은 기본 역할을 참조하세요.

API 키를 만들려면 다음 안내를 따르세요.

  1. Cloud Console에서 API 및 서비스 → 사용자 인증 정보 패널로 이동합니다.

  2. 사용자 인증 정보 만들기를 선택한 후 드롭다운 메뉴에서 API 키를 선택합니다.

    API 키 생성 대화상자에 새로 생성된 키가 표시됩니다.

    API 키는 대문자, 소문자, 숫자, 대시가 포함된 긴 문자열입니다(예: a4db08b7-5729-4ba9-8c08-f2df493465a1).

키를 복사하여 안전하게 보호해야 합니다. 테스트 키를 사용 중이고 나중에 이를 삭제하려는 경우가 아니면 애플리케이션 및 API 키 제한사항을 추가하세요.

API 키 사용

다음 형식에 따라 API 키를 REST API 호출에 쿼리 매개변수로 전달합니다. API_KEY를 내 API 키로 바꿉니다.

key=API_KEY

예를 들어 documents.analyzeEntities Cloud Natural Language API 요청에 API 키를 전달하려면 다음 명령어를 입력합니다.

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

API 키 보호

애플리케이션에서 API 키를 사용하는 경우 저장 및 전송 중에 안전하게 보호되도록 해야 합니다. 사용자 인증 정보를 공개적으로 노출하면 계정이 유출되어 계정에 예상치 못한 비용이 부과될 수 있습니다. API 키를 안전하게 보호하기 위해서는 다음 권장사항을 따르세요.

  • 코드에 직접 API 키를 삽입하지 않습니다. 코드에 삽입된 API 키는 실수로 일반에 노출될 수 있습니다. 예를 들어 공유 코드에서 키를 삭제하는 것을 깜빡하는 경우가 있습니다. 애플리케이션에 API 키를 삽입하는 대신 환경 변수에 저장하거나 애플리케이션의 소스 트리 외부에 있는 파일에 저장하세요.

  • 애플리케이션의 소스 트리 내에 있는 파일에 API 키를 저장하지 않습니다. API 키를 파일에 저장할 경우, 키가 소스 코드 제어 시스템에 포함되지 않도록 애플리케이션의 소스 트리 외부에 파일을 보관하세요. 이는 GitHub와 같은 공개 소스 코드 관리 시스템을 사용하는 경우에 특히 중요합니다.

  • 애플리케이션 및 API 키 제한사항을 설정합니다. 제한사항을 추가하면 API 키 유출로 인한 피해를 줄일 수 있습니다.

  • 공격에 노출되는 것을 최소화하기 위해 불필요한 API 키는 삭제합니다.

  • API 키를 주기적으로 다시 생성합니다. 사용자 인증 정보 페이지에서 키마다 키 다시 생성을 클릭하여 API 키를 다시 생성할 수 있습니다. 그런 후 새로 생성된 키를 사용하도록 애플리케이션을 업데이트하세요. 이전 키는 교체용 키를 생성한 후에도 24시간 동안 계속 작동합니다.

  • 코드를 공개적으로 릴리스하기 전에 검토합니다. 코드를 일반에 공개하기 전에 코드에 API 키 또는 다른 비공개 정보가 포함되지 않았는지 확인하세요.

API 키 제한사항 적용

API 키는 기본적으로 무제한 상태입니다. 무제한 키는 어디서나 사용할 수 있으므로 안전하지 않습니다. 프로덕션 애플리케이션의 경우 애플리케이션 제한사항API 제한사항을 모두 설정해야 합니다.

API 키 제한사항을 추가하려면 다음 안내를 따르세요.

  1. Cloud Console에서 API 및 서비스 → 사용자 인증 정보 패널로 이동합니다.

  2. 기존 API 키 이름을 선택합니다.

애플리케이션 제한사항 추가

애플리케이션 제한사항은 API 키를 사용할 수 있는 웹사이트, IP 주소 또는 앱을 지정합니다. 애플리케이션 유형을 기준으로 애플리케이션 제한사항을 추가합니다. API 키별로 제한사항 유형을 하나만 설정할 수 있습니다.

애플리케이션의 요구 사항에 따라 제한사항 유형을 선택합니다.

  • 없음은 테스트 목적으로만 사용합니다.

  • 지정된 페이지만 API를 호출할 수 있도록 웹브라우저에서 실행되는 API 클라이언트에는 HTTP 리퍼러를 사용합니다. 이러한 유형의 애플리케이션은 API 키를 공개적으로 노출하므로, 대신 서비스 계정을 사용하는 것이 좋습니다. 아래의 HTTP 제한사항 추가 섹션을 참조하세요.

  • API 키 액세스를 특정 IP 주소로 제한하려면 IP 주소를 사용합니다.

  • Android 애플리케이션의 경우에는 Android 앱을 사용합니다. 이 옵션을 사용하려면 패키지 이름과 SHA-1 서명 인증서 디지털 지문을 추가해야 합니다.

  • iOS 애플리케이션의 경우에는 iOS 앱을 사용합니다. 이 옵션을 사용하려면 API 호출을 특정 iOS 번들로 제한하도록 iOS 번들 식별자를 하나 이상 추가해야 합니다.

HTTP 제한사항 추가

웹 애플리케이션에서 사용하는 API 키에는 HTTP 제한사항이 있어야 합니다. HTTP 제한사항을 추가하려면 다음 안내를 따르세요.

  • 애플리케이션 제한사항 섹션에서 HTTP 리퍼러(웹 사이트)를 선택합니다.

  • 웹사이트 제한사항 섹션에 하나 이상의 제한사항을 입력합니다.

  • 도메인에서 HTTP와 HTTPS가 모두 지원되는 경우 두 가지 제한사항을 모두 개별적으로 추가해야 합니다.

  • 하위 도메인 또는 경로에 대해서는 와일드 카드 문자(*)를 사용할 수 있습니다.

다음 표에서는 제한 수준이 가장 높은 것부터 가장 낮은 것까지 예시 시나리오와 제한사항을 보여줍니다. 사용 사례에 적합한 가장 제한적인 예를 사용하는 것이 좋습니다.

시나리오 제한사항
특정 URL을 허용합니다.

정확한 경로를 사용해서 단일 제한사항을 추가합니다. 예를 들면 다음과 같습니다.

  • https://www.example.com/path
  • http://www.example.com/path/path
단일 하위 도메인 또는 네이키드 도메인의 모든 URL을 허용합니다.

전체 도메인을 허용하려면 최소 2개 이상의 제한사항을 설정해야 합니다.

  1. 끝에 슬래시를 입력하지 않고 도메인의 제한사항을 설정합니다. 예를 들면 다음과 같습니다.
    • https://www.example.com
    • http://sub.example.com
    • http://example.com
  2. 경로에 대한 와일드 카드가 포함된 도메인의 두 번째 제한사항을 설정합니다. 예를 들면 다음과 같습니다.
    • https://www.example.com/*
    • http://sub.example.com/*
    • http://example.com/*
  3. 도메인에서 HTTP와 HTTPS가 모두 허용될 경우, 추가 제한사항을 개별적으로 추가해야 합니다.
단일 도메인에서 모든 하위 도메인 URL을 허용합니다.

최소한 2개 이상의 제한사항을 설정해야 합니다.

  1. 하위 도메인에 와일드 카드를 사용하고, 끝에는 슬래시를 입력하지 않고 도메인의 제한사항을 설정합니다. 예를 들면 다음과 같습니다.
    • https://*.example.com
  2. 경로에 대한 와일드 카드가 포함된 도메인의 두 번째 제한사항을 설정합니다. 예를 들면 다음과 같습니다.
    • https://*.example.com/*
  3. 도메인에서 HTTP와 HTTPS가 모두 허용될 경우, 추가 제한사항을 개별적으로 추가해야 합니다.

API 제한사항 추가

API 제한사항은 API 키를 사용해서 호출할 수 있는 API를 지정합니다. 프로덕션 애플리케이션에서 사용하는 모든 API 키에는 API 제한사항이 있어야 합니다.

API 제한사항을 설정하려면 다음 안내를 따르세요.

  1. API 제한사항 섹션에서 키 제한을 클릭합니다.

  2. 드롭다운에서 API 키가 액세스하는 데 사용될 모든 API를 선택합니다.

  3. 저장을 클릭합니다.

프로젝트별 한도

프로젝트당 300개의 API 키를 만들 수 있습니다. 이는 시스템 한도이며 할당량 증가 요청을 사용하여 변경될 수 없습니다.

더 많은 API 키가 필요하면 여러 프로젝트 간에 샤딩되어야 합니다.

다음 단계