공지사항: 2025년 4월 15일 전에 Earth Engine 사용을 위해 등록된 모든 비상업용 프로젝트는 Earth Engine 액세스를 유지하기 위해 비상업용 자격 요건을 인증해야 합니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

인증 및 초기화

클라이언트 라이브러리를 통해 Earth Engine에 요청을 보내려면 먼저 인증하고 결과 사용자 인증 정보를 사용하여 Earth Engine 클라이언트를 초기화해야 합니다.

Earth Engine 코드 편집기 및 JavaScript

인증 및 초기화는 Code 편집기에서 자동으로 처리됩니다. Code 편집기 오른쪽 상단의 로그인에서 Cloud 프로젝트를 통해 요청을 라우팅하도록 선택할 수 있습니다.

JavaScript API를 사용하고 있다면 (코드 편집기 외부) ee.data의 인증 도우미 중 하나 (예: ee.data.authenticateViaPopup())를 사용한 다음 이 예와 같이 ee.initialize()를 사용합니다.

Python 및 명령줄

Earth Engine Python 클라이언트 라이브러리를 사용하기 전에 인증(ID 확인)을 거쳐 결과 사용자 인증 정보를 사용하여 Python 클라이언트를 초기화해야 합니다. 인증 흐름은 Cloud 프로젝트를 사용하여 인증하며 유료 사용뿐만 아니라 무료 (비상업용) 사용에도 사용됩니다. 인증 및 초기화하려면 다음을 실행합니다.

    ee.Authenticate()
    ee.Initialize(project='my-project')

그러면 먼저 환경에 가장 적합한 인증 모드가 선택되고 스크립트의 액세스를 확인하라는 메시지가 표시됩니다. 사용자 인증 정보가 이미 있는 경우 자동으로 재사용됩니다. ee.Authenticate(force=True)를 실행하여 새 사용자 인증 정보를 만듭니다.

초기화 단계에서는 ee.Authenticate()에서 생성되었거나 Google 기본 사용자 인증 정보로 사전 존재하는 유효한 사용자 인증 정보가 있는지 확인합니다. 그런 다음 백엔드 서버에서 지원하는 메서드로 Python 클라이언트 라이브러리를 초기화합니다. 소유하고 있거나 사용 권한이 있는 프로젝트를 제공해야 합니다. 프로젝트를 등록하고 Earth Engine API를 사용 설정하려면 Cloud 프로젝트 설정을 참고하세요. 이 프로젝트는 모든 Earth Engine 작업을 실행하는 데 사용됩니다.

명령줄에서 이에 상응하는 호출은 earthengine authenticate입니다. 사용자 인증 정보가 만료되었거나 잘못된 경우 earthengine authenticate --force를 실행해야 할 수 있습니다. 명령줄 호출은 각 호출 시 초기화되며 --project 인수를 사용하여 프로젝트를 설정할 수 있습니다.

earthengine set_project {my-project}를 실행하여 향후 모든 호출에 대해 프로젝트를 구성할 수도 있습니다. 명령줄과 ee.Initialize()는 프로젝트가 직접 지정되지 않을 때마다 이를 사용합니다. gcloud를 통한 인증을 사용하는 경우 (아래 참고) gcloud auth application-default set-quota-project {my-project}로 설정된 프로젝트가 최종 케이스로 사용됩니다.

인증 세부정보

Earth Engine 인증 흐름의 목표는 로그인한 계정에서 보안 '토큰'을 가져와 저장하여 스크립트에 데이터에 액세스할 권한을 부여하는 것입니다. 보안상의 이유로 Google의 인증 시스템은 이러한 토큰을 안전하게 보호할 수 있는 시스템에만 전달합니다. 아래의 기술 메모를 참고하세요.

관련 시스템의 종류에 대한 민감도 때문에 특정 상황에 따라 진행 방법이 다릅니다. 대부분의 옵션은 auth_mode 매개변수(명령줄에서 ee.Authenticate(auth_mode=...) 또는 earthengine authenticate --auth_mode=...)로 제어됩니다.

환경에 Google 사용자 인증 정보가 이미 있는 경우 ee.Authenticate()를 전혀 호출하지 않아도 됩니다. Google Cloud VM, App Engine, 기타 환경은 사용 가능한 '대기 모드 사용자 인증 정보'를 제공하며 gcloud auth application-default login도 이를 만듭니다.

그러나 호환성을 극대화하려면 모든 스크립트의 시작 부분에 ee.Authenticate()를 사용하는 것이 좋습니다. auth_mode 매개변수가 없으면 대부분의 상황에서 작동하도록 설계되었지만 기본 모드가 작동하지 않으면 아래 세부정보를 따르세요. 기본 모드는 다음과 같이 선택됩니다.

Google Colab 메모장에서 실행하는 경우 colab
Colab 이외의 다른 Jupyter 노트북에서 실행하는 경우 notebook
localhost: 웹브라우저가 감지되고 gcloud 바이너리가 설치되지 않은 경우
그렇지 않으면 gcloud입니다. 이 모드를 사용하려면 gcloud를 설치해야 합니다.

빠른 참조 가이드 및 표

이 결정 가이드에서는 ee.Authenticate()에서 선택한 기본 모드가 작동하지 않는 경우 가능한 옵션을 간략히 설명합니다. 예를 들어 다른 노트북 환경에서 실행하는 경우 notebook를 명시적으로 지정해야 할 수 있습니다.

로컬 환경
- '로컬'은 내 앞에 있는 머신 또는 더 정확하게는 웹브라우저가 실행 중인 것과 동일한 머신의 Python 셸 또는 Python 메모장에서 코드를 실행하고 있음을 의미합니다. 여기에는 Python과 브라우저가 모두 동일한 (원격) 머신에 있는 원격 데스크톱 상황이 포함됩니다.
- auth_mode=localhost를 사용하는 것이 가장 쉽고 gcloud가 설치되어 있지 않은 경우 기본적으로 선택되지만 스크립트는 로컬 환경에서만 작동합니다.
- auth_mode=gcloud와 auth_mode=notebook도 모두 사용할 수 있습니다.
원격 환경.
- '원격'은 브라우저가 하나의 (로컬) 머신에 있지만 코드가 원격 워크스테이션이나 웹 기반 노트북과 같이 다른 곳에서 실행되고 있음을 의미합니다.
- Colab의 경우 auth_mode=colab를 사용하고, 다른 API를 호출하도록 scopes를 설정해야 하는 경우 gcloud를 사용합니다.
- 원격 머신과 로컬 머신 모두에 gcloud를 설치할 수 있는 경우 auth_mode=gcloud를 사용합니다.
- 인증 프로젝트를 사용할 수 있는 경우 (아래 참고) auth_mode=notebook를 사용하세요.
- 그렇지 않고 동일한 머신에서 프로젝트를 사용하거나 gcloud를 설치하거나 Colab을 사용하거나 브라우저를 사용할 수 없는 경우 다음 단계를 따르세요.
- 프로젝트 만들기에 관해 관리자에게 다시 문의합니다. 예를 들면 다음과 같습니다.
  - 관리자에게 소유자, 편집자 또는 OAuth 구성 편집자로서 프로젝트를 구성해 달라고 요청
  - 또는 관리자에게 프로젝트를 만들 권한을 부여해 달라고 요청하세요.

다음 표에는 각 모드에서 지원되는 기능 조합이 나와 있습니다.

	로컬인가요, 원격인가요?	프로젝트 필요	설정 가능한 범위	로컬 CLI 필요	프로젝트 소유자
`localhost`	로컬	Y	예	아니요	N
`colab`	리모컨	Y	아니요	아니요	N
`gcloud`	전부	Y	예	아니요	N
`notebook`	전부	Y	예	아니요	Y

서비스 계정 및 Compute Engine 사용자 인증 정보

ee.Initialize()는 Earth Engine 사용자 인증 정보 (ee.Authenticate()가 ~/.config/earthengine/credentials에 저장)를 사용하거나 google.auth.default()에서 사용자 인증 정보를 가져오지만, 필요한 경우 credentials= 인수를 전달하여 다른 위치의 사용자 인증 정보를 사용하여 이러한 기본값을 우회할 수 있습니다.

무인으로 실행될 Python 코드를 인증하는 경우 사용자 계정 대신 서비스 계정으로 인증하는 것이 좋습니다. Earth Engine에서 서비스 계정을 사용하는 방법은 이 문서를 참고하세요. 다른 메서드로는 Colab 인증 모듈의 authenticate_service_account 및 서비스 계정으로 인증하기 위한 Cloud 가이드에 설명된 메서드가 있습니다.

코드가 Compute Engine VM에서 실행되는 경우 환경에 기본 서비스 계정이 생성되며 ee.Initialize()은 기본적으로 이 계정을 사용합니다. VM을 시작한 클라우드 프로젝트가 Earth Engine (상업용 또는 비상업용)에서 사용하도록 등록되어 있지 않은 경우 Earth Engine을 사용하도록 서비스 계정을 등록해야 할 수 있습니다.

모드에 관한 세부정보

auth_mode=colab. ee.Authenticate()는 필요한 경우 colab.auth.authenticate_user()를 실행하여 Colab에서 지원하는 기본 사용자 인증 정보를 만들거나 가져옵니다. 사용자 인증 정보는 항상 cloud-platform 범위를 사용하며 다른 Cloud API를 호출하는 데도 사용할 수 있습니다.

auth_mode=gcloud. 이렇게 하면 인증이 gcloud 도구에 위임되며 기본 Earth Engine 범위 (earthengine, cloud-platform, drive) 또는 scopes 인수의 범위로 gcloud auth application-default login를 실행하는 것과 동일합니다. gcloud 모드는 로컬 케이스와 원격 케이스 모두에서 작동합니다.

gcloud 모드 단계별 안내 (로컬 및 원격 케이스)

로컬 머신에 gcloud가 설치되어 있는지 확인합니다.
- 터미널에서 gcloud help를 실행합니다. gcloud가 설치되어 있지 않으면 이 안내에 따라 gcloud를 설치합니다.
로컬 머신 터미널
- 터미널에서 earthengine authenticate를 실행합니다.
- 명령어 출력은 사용자 인증 정보를 가져오는 데 gcloud가 사용되고 있음을 나타냅니다.
- 브라우저 창이 열리고 계정 선택 페이지가 표시됩니다. 브라우저가 자동으로 열리지 않으면 URL을 클릭합니다.
브라우저: 계정 선택
- 인증에 사용할 계정을 선택합니다.
브라우저: 동의 화면
- 요청된 범위를 부여할지 여부를 표시하고 '허용'을 클릭합니다.
브라우저: 확인 화면
- 브라우저에 인증되었음을 확인하는 페이지가 표시되고 터미널 창의 earthengine authenticate 명령어에 '승인 토큰을 저장했습니다.'라는 메시지가 표시됩니다.
- 원격인 경우 웹페이지에 Python 환경에 다시 붙여넣을 코드가 표시됩니다.
초기화를 진행합니다.

auth_mode=localhost. gcloud가 설치되지 않은 경우의 gcloud와 유사한 흐름입니다. gcloud와 동일한 단계를 실행하지만 로컬 케이스에만 작동합니다. 선택적 인터넷 포트 번호(예: localhost:8086)를 제공하거나 localhost:0를 사용하여 포트를 자동 선택할 수 있습니다. 기본 포트는 8085입니다.

auth_mode=notebook. 이는 로컬 명령줄을 사용할 수 없는 원격 상황에서 작동하도록 설계된 범용 모드입니다. 그러면 Notebook 인증자 페이지로 이동하여 '인증 프로젝트'를 선택하거나 만들어야 합니다. 아래의 세부정보와 문제 해결 가이드를 참고하세요. ee.Initialize()에 전달된 프로젝트는 이와 일치하지 않아도 됩니다. 여러 노트북에서 서로 다른 프로젝트에서 작업하는 동안 인증을 위해 동일한 프로젝트를 유지할 수 있습니다. 프로젝트를 ee.Initialize()에 명시적으로 전달하는 것이 좋지만 기본적으로 인증 프로젝트가 사용됩니다.

노트북 모드 단계별 안내

브라우저: 노트북
1. 노트북 코드 셀에서 다음 코드를 실행하여 '노트북' 모드를 사용하여 인증 흐름을 시작합니다.
```
import ee
ee.Authenticate()
```
  셀 출력의 링크를 클릭하여 새 탭에서 Notebook Authenticator 페이지를 엽니다.
브라우저: 노트북 인증자
1. 올바른 사용자 계정이 표시되는지 확인합니다.
2. 인증에 사용할 Google Cloud 프로젝트를 선택합니다. 새 프로젝트를 만들어야 하는 경우 'ee-xyz'라는 이름 지정 규칙을 사용하는 것이 좋습니다. 여기서 xyz는 일반적인 Earth Engine 사용자 이름입니다. Cloud 프로젝트를 선택하거나 만들 수 없는 경우 아래의 문제 해결 섹션을 참고하세요.
3. 'Generate Token'(토큰 생성)을 클릭합니다.
브라우저: 계정 선택
- 계정 선택 페이지가 표시됩니다. 노트북에서 액세스 권한을 부여할 사용자 계정을 클릭합니다.
브라우저: 경고 페이지
- Google에서 앱(즉, 노트북의 코드)을 만들지 않았음을 나타내는 경고 페이지가 표시됩니다. 확인하려면 '계속'을 클릭합니다.
브라우저: 동의 화면
- 요청된 범위를 부여할지 여부를 표시하고 계속을 클릭합니다.
브라우저: 승인 코드 화면
- 승인 인증 코드 복사
브라우저: 노트북
- 노트북 탭으로 다시 전환하고 인증 코드를 노트북 셀 출력에 붙여넣습니다.
- 셀 출력에 '승인 토큰을 저장했습니다.'라고 표시됩니다.
초기화를 진행합니다.

노트북 모드에는 거의 사용되지 않는 quiet 매개변수가 있습니다. 이 매개변수를 설정하면 '비대화형'으로 실행되며 사용자에게 인증 코드를 입력하라는 메시지를 표시하지 않고 기다리지 않습니다. 대신 코드를 저장하기 위해 실행할 명령어를 제공합니다.

인증 프로젝트

노트북 모드에서 사용되는 인증 프로젝트의 소유자, 편집자 또는 OAuth 구성 편집자여야 합니다. 특히 소규모 팀의 경우 Notebook Authenticator 페이지에서 사용하는 인증 프로젝트가 다른 작업에 사용하는 기본 프로젝트와 동일할 수 있습니다.

보안 문제로 인해 인증 프로젝트의 'OAuth 클라이언트 구성'은 일회성 설정입니다. 나 또는 다른 사용자가 다른 이유로 프로젝트에 OAuth 클라이언트를 설정한 경우 OAuth 클라이언트를 삭제할 수 없으며 '호환되지 않는 OAuth2 클라이언트 구성'이라는 오류가 표시됩니다. 인증에 다른 프로젝트를 사용하거나 위의 colab, localhost 또는 gcloud 모드를 사용해야 합니다.

문제 해결

Cloud 프로젝트를 만들 수 없는 경우 어떻게 해야 하나요?

일부 조직에서는 Cloud 프로젝트를 만들 수 있는 사용자를 제어합니다. 프로젝트를 만들려고 할 때 노트북 인증자 페이지에 오류가 표시되면 다음과 같은 몇 가지 방법을 시도해 보세요.

직접 프로젝트를 만들어 필요한 권한이 있는지 확인해 보세요.
조직의 관리자에게 문의하여 프로젝트를 만들 수 있는 프로세스를 알아보세요.
조직 외 계정에서 프로젝트를 만들고 업무에 사용하는 계정을 프로젝트의 소유자로 추가합니다. 참고: 일부 조직에서는 외부 프로젝트에서 OAuth 클라이언트에 액세스하는 것을 방지하는 보안 정책을 시행하고 있습니다.

오류: '이전에 XXX 프로젝트에서 Earth Engine API를 사용한 적이 없거나 사용 중지되었습니다'

먼저 ee.Initialize() 또는 명령줄에서 프로젝트를 구성했는지 확인합니다. Cloud 및 Colab에서 제공하는 기본 프로젝트에는 Earth Engine이 사용 설정되어 있지 않습니다. 두 번째로, 프로젝트에서 Earth Engine API가 사용 설정되어 있는지 확인합니다.

오류: '프로젝트에 호환되지 않는 OAuth2 클라이언트 구성이 있습니다'

Cloud 프로젝트에는 OAuth2 클라이언트 구성을 하나만 보유할 수 있습니다. 사용자 인증 정보 페이지에서 OAuth 2.0 클라이언트 ID를 확인하여 Cloud 프로젝트에 OAuth2 클라이언트 구성이 설정되어 있는지 확인할 수 있습니다. Notebook 인증자에 의해 이미 호환되는 구성이 설정된 다른 Cloud 프로젝트를 선택하거나 OAuth2 클라이언트가 없는 Cloud 프로젝트를 선택하거나 만들어야 합니다. 인증자가 이 프로젝트를 자동으로 구성합니다. 안타깝게도 OAuth 시스템에서는 사용자가 구성을 삭제할 수 없으므로 다른 프로젝트를 사용해야 합니다. 이 프로젝트는 다른 Earth Engine 작업에 사용되는 프로젝트와 동일할 필요는 없습니다. 이 오류는 Colab 모드에서는 발생하지 않습니다.

오류: 'gcloud 실패. 위에서 오류가 있는지 확인하고 필요한 경우 gcloud를 설치하세요.'

이 오류는 gcloud가 설치되어 있지 않거나 PATH에 없는 경우 발생할 수 있습니다. 노트북 코드 셀 내에서 ee.Authenticate(auth_mode='gcloud')를 호출하는 경우에도 이 문제가 발생할 수 있습니다. 대신 ee.Authenticate()를 사용하세요. 그러면 기본적으로 노트북 모드 인증이 사용됩니다. 프로젝트를 만들 수 없는 경우 위의 해결 방법을 참고하세요.

gcloud를 설치할 로컬 머신에 액세스할 수 없는 경우 어떻게 해야 하나요?

로컬 터미널에 액세스할 수 없는 웹 전용 환경에서 작업하고 있지만 원격 터미널을 사용해야 하는 경우에도 earthengine authenticate --auth_mode=notebook 명령어를 실행하여 노트북 모드를 트리거하여 명령줄 도구를 초기화할 수 있습니다.

오류 400: redirect_uri_mismatch

웹브라우저에 액세스할 수 없는 원격 머신에서 인증하는 경우 이 오류가 발생할 수 있습니다. 명령줄에서 earthengine authenticate를 실행하는 경우 --quiet를 추가하거나 Python 클라이언트를 사용하는 경우 ee.Authenticate(quiet=True)를 추가해 보세요. 이렇게 하려면 웹브라우저에 액세스할 수 있는 머신에서 gcloud로 인증해야 합니다.

오류: '애플리케이션이 로컬 애플리케이션 기본 사용자 인증 정보를 사용하여 인증하고 있습니다. earthengine.googleapis.com API에는 기본적으로 설정되지 않은 할당량 프로젝트가 필요합니다."

이 오류는 Earth Engine에서 프로젝트 ID를 확인할 수 없는 경우 발생할 수 있습니다. Google Cloud 문제 해결 옵션이 작동하지 않으면 earthengine set_project YOUR_PROJECT_ID 또는 gcloud auth application-default set-quota-project YOUR_PROJECT_ID를 실행해 보세요.

기술 참고사항

기술적으로 궁금한 경우: 이러한 다양한 사용자 인증 정보 생성 메커니즘의 필요성은 알려진 신뢰할 수 있는 환경에 사용자 인증 정보를 전달해야 하는 필요성에서 비롯됩니다. 다음은 위의 다양한 케이스에 대한 간단한 설명입니다.

이전에는 어디서나 붙여넣을 수 있는 토큰을 제공하는 paste 모드가 있었지만 너무 위험하다고 간주되어 더 이상 사용할 수 없습니다.
colab: auth.authenticate_user()에서 'Colab' 인증 클라이언트(노트북 환경 자체)와 사용자 인증 정보를 공유하라는 메시지가 표시됩니다. 그런 다음 google.auth.default()를 통해 사용할 수 있으며 ee.Initialize()에서 사용합니다.
localhost: 사용자 인증 정보가 브라우저에서 로컬 머신의 포트로 전달됩니다. 이 경우 엔드 투 엔드 보안은 로컬 머신이 손상되지 않았는지에 따라 달라집니다. 표시되는 인증 클라이언트는 'Earth Engine Authenticator'입니다.
gcloud: gcloud 참조에 설명된 --launch-browser 흐름을 사용하고 원격 머신인 경우 --no-launch-browser를 사용합니다. 사용된 인증 클라이언트는 'Google 인증 라이브러리'입니다.
notebook: 작업에 맞게 새 인증 클라이언트가 생성됩니다. 동의 페이지에 이메일 주소가 표시됩니다. 이 클라이언트는 '개발' 모드로 설정되어 있습니다. 이는 이전 붙여넣기 모드 토큰을 허용하는 특수한 사례입니다. 이러한 클라이언트는 많은 사용자와 공유할 수 없으므로 자체 프로젝트를 사용해야 합니다.