認証と初期化

クライアント ライブラリを介して Earth Engine にリクエストを行う前に、認証を行い、結果の認証情報を使用して Earth Engine クライアントを初期化する必要があります。

Earth Engine コードエディタと JavaScript

認証と初期化はコードエディタで自動的に処理されます。コードエディタの右上にあるログインから、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
• ウェブブラウザが検出され、gcloud バイナリがインストールされていない場合は localhost
• それ以外の場合は gcloud。このモードでは、gcloud をインストールする必要があります。

クイック リファレンス ガイドと表

この決定ガイドでは、ee.Authenticate() によって選択されたデフォルト モードが機能しない場合に考えられるオプションについて説明します。たとえば、他のノートブック環境で実行している場合は、notebook を明示的に指定する必要があります。

• ローカル環境。
  • 「ローカル」とは、目の前のマシン（より正確には、ウェブブラウザが実行されているマシン）の Python シェルまたは Python ノートブックでコードを実行していることを意味します。これには、Python とブラウザの両方が同じ（リモート）マシンにあるリモート デスクトップの状況も含まれます。
  • auth_mode=localhost を使用するのが最も簡単で、gcloud がインストールされていない場合はデフォルトで選択されますが、スクリプトはローカル環境でのみ機能します。
  • auth_mode=gcloud と auth_mode=notebook の両方も利用できます。
• リモート環境。
  • 「リモート」とは、ブラウザは 1 台の（ローカル）マシンにあり、コードはリモート ワークステーションやウェブベースのノートブックなど、別の場所で実行されていることを意味します。
  • Colab の場合は auth_mode=colab を使用します。他の API を呼び出すために scopes を設定する必要がある場合は、gcloud を使用します。
  • リモートマシンとローカルマシンの両方に gcloud をインストールできる場合は、auth_mode=gcloud を使用します。
  • 認証プロジェクトを使用できる場合は（下記を参照）、auth_mode=notebook を使用します。
  • それ以外の場合（プロジェクトを使用できない、gcloud をインストールできない、Colab を使用できない、同じマシンでブラウザを使用できない場合）:
  • プロジェクトの作成について（再度）管理者に相談します。例:
    • 管理者に対して、プロジェクトの構成（オーナー、編集者、OAuth 構成編集者）を依頼する
    • または、プロジェクトを作成する権限を付与するよう管理者に依頼してください。

次の表は、各モードでサポートされている機能の組み合わせを示しています。

	ローカルまたはリモート？	Project Needed	設定可能なスコープ	ローカル CLI が必要	プロジェクト オーナー
localhost	ローカル	Y	○	N	N
colab	リモコン	Y	N	N	N
gcloud	両方	Y	○	N	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 の起動に使用された Cloud プロジェクトが Earth Engine（商用または非営利）での使用に登録されていない場合は、Earth Engine を使用するようにサービス アカウントを登録する必要があります。

モードの詳細

auth_mode=colab。ee.Authenticate() は、必要に応じて colab.auth.authenticate_user() を実行して、Colab でサポートされているデフォルトの認証情報を作成または取得します。認証情報では常に cloud-platform スコープが使用され、他の Cloud APIs の呼び出しにも使用できます。

auth_mode=gcloud。これにより、認証が gcloud ツールに委任されます。これは、デフォルトの Earth Engine スコープ（earthengine、cloud-platform、drive）または scopes 引数のスコープを使用して gcloud auth application-default login を実行するのと同じです。gcloud モードは、ローカルとリモートの両方で動作します。

gcloud モードの手順ガイド（ローカルとリモートの場合）

次の手順では、ローカルマシンのコマンドラインから認証する方法について説明します。

1. ローカルマシンに gcloud がインストールされていることを確認します。
   • ターミナルで gcloud help を実行します。gcloud がインストールされていない場合は、こちらの手順に沿って gcloud をインストールします。
2. ローカル マシン ターミナル
   • ターミナルで earthengine authenticate を実行します。
   • コマンド出力には、gcloud を使用して認証情報を取得していることが示されます。
   • ブラウザ ウィンドウが開き、アカウント選択ページが表示されます。ブラウザが自動的に開かない場合は、URL をクリックします。
3. ブラウザ: アカウントの選択
   • 認証に使用するアカウントを選択します。
4. ブラウザ: 同意画面
   • リクエストされたスコープを付与するかどうかを指定し、[許可] をクリックします。
5. ブラウザ: 確認画面
   • ブラウザに認証済みであることを確認するページが表示され、ターミナル ウィンドウの earthengine authenticate コマンドに「Successfully saved authorization token.」と表示されます。
   • リモートの場合、ウェブページにコードが表示されるので、そのコードを Python 環境に貼り付けます。
6. 初期化を続行します。

auth_mode=localhost。これは、gcloud がインストールされていない場合の gcloud のようなフローです。gcloud と同じ手順を実行しますが、ローカルの場合にのみ機能します。オプションのインターネット ポート番号（例: localhost:8086）を指定するか、localhost:0 を使用してポートを自動選択できます。デフォルトのポートは 8085 です。

auth_mode=notebook。これは、ローカル コマンドラインが使用できないリモート環境で動作するように設計された汎用モードです。Notebook Authenticator ページに移動します。ここで、「認証プロジェクト」を選択または作成する必要があります。詳細とトラブルシューティング ガイドについては、以下をご覧ください。ee.Initialize() に渡されるプロジェクトはこれと一致する必要はありません。異なるノートブックで異なるプロジェクトを操作しながら、認証に同じプロジェクトを使用できます。プロジェクトを ee.Initialize() に明示的に渡すことをおすすめしますが、デフォルトでは認証プロジェクトが使用されます。

ノートブック モードの手順ガイド

次の手順では、ノートブック内から認証する方法について説明します。

1. ブラウザ: Notebook
   1. ノートブックのコードセルで次のコードを実行して、「notebook」モードで認証フローを開始します。

      import ee
      ee.Authenticate()

      セル出力のリンクをクリックして、新しいタブで Notebook Authenticator ページを開きます。
2. ブラウザ: Notebook Authenticator
   1. 正しいユーザー アカウントが表示されていることを確認します。
   2. 認証に使用する Google Cloud プロジェクトを選択します。新しいプロジェクトを作成する必要がある場合は、「ee-xyz」という命名規則をおすすめします。ここで、xyz は通常の Earth Engine ユーザー名です。（Cloud プロジェクトを選択または作成できない場合は、下記のトラブルシューティング セクションをご覧ください）。
   認証に必要な IAM 権限（プロジェクトのオーナーまたは編集者、または 割り当てられている他の IAM ロールに加えて「OAuth 構成編集者」の事前定義ロールなど）が割り当てられている必要があります。チームの他のユーザーがこのプロジェクトで認証構成をすでに作成している場合は、追加の警告が表示されます。クリエイターが信頼できる共同編集者である場合にのみ、続行してください。
   3. [トークンを生成] をクリックします。
3. ブラウザ: アカウントの選択
   • アカウント選択ページが表示されます。ノートブックからアクセス権を付与するユーザー アカウントをクリックします。
4. ブラウザ: 警告ページ
   • 警告ページが表示され、Google がアプリ（ノートブック内のコード）を作成していないことが示されます。[続行] をクリックして確認します。
5. ブラウザ: 同意画面
   • リクエストされたスコープを付与するかどうかを指定し、[続行] をクリックします。
6. ブラウザ: 認証コード画面
   • 認証確認コードをコピーする
7. ブラウザ: Notebook
   • ノートブック タブに戻り、ノートブック セルの出力に確認コードを貼り付けます。
   • セルの出力には、「Successfully saved authorization token.」と表示されます。
8. 初期化を続行します。

ノートブック モードには、ほとんど使用されない quiet パラメータがあります。このパラメータを設定すると、「非対話型」で実行され、認証コードの入力を求めるプロンプトが表示されません。代わりに、コードを保存するための実行コマンドが表示されます。

認証プロジェクト

ノートブック モードで使用される認証プロジェクトのオーナー、編集者、または OAuth 構成編集者である必要があります。多くの場合、特に小規模なチームでは、[Notebook Authenticator] ページで使用する認証プロジェクトは、他の作業に使用するプライマリ プロジェクトと同じにできます。

セキュリティ上の懸念から、認証プロジェクトの「OAuth クライアント構成」は 1 回限りの設定です。他の理由でプロジェクトに OAuth クライアントを設定している場合、そのクライアントは削除できません。また、「互換性のない OAuth2 クライアント構成」というエラーが表示されます。認証には別のプロジェクトを使用するか、上記の colab、localhost、gcloud のいずれかのモードを使用する必要があります。

スコープの詳細

Earth Engine のデフォルトの認証設定には、使用可能なすべてのスコープが含まれています。デフォルトが要件を満たしている場合は、このセクションをスキップできます。

Earth Engine スコープ: OAuth 2.0 スコープは、アプリケーションがユーザーの代わりにアクセスできるリソースとオペレーションのセットを定義して制限します。OAuth を使用して Earth Engine で認証を行う場合は、次のスコープの 1 つ以上をリクエストする必要があります。

• https://www.googleapis.com/auth/earthengine: Earth Engine のアセットとリソースに対する読み取り / 書き込みアクセス権。アセットの作成、変更、削除、アセット権限の管理、エクスポート タスクの実行に必要です。
• https://www.googleapis.com/auth/earthengine.readonly: Earth Engine アセットに対する読み取り専用アクセス権。

どちらのスコープでも、スクリプトの実行と計算の実行（式の評価や地図の可視化のレンダリングなど）が可能です。

Google Cloud とドライブのスコープ: Earth Engine のクエリまたはスクリプトが外部データまたはアセットを参照する場合は、認証情報にこれらのサービスに対応する適切なスコープも含まれている必要があります。

• Cloud Storage（GCS）（Cloud Storage バケットからの読み取りまたは Cloud Storage バケットへの書き込み時（Cloud-Optimized GeoTIFF の読み込みやタスク出力のエクスポートなど））:
  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.read_only
• BigQuery（BQ）（テーブルの読み取り時または BigQuery へのエクスポートの書き込み時）:
  • https://www.googleapis.com/auth/bigquery
• Google ドライブ（Google ドライブにアクセスする場合、または Google ドライブにデータをエクスポートする場合）:
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.readonly

Google Cloud には、すべての Google Cloud サービスを対象とする広範なスコープもあります。

• Cloud Platform（Earth Engine、Cloud Storage、BigQuery を含む Google Cloud サービスへの広範なアクセス。Google ドライブは別の Workspace サービスであり、これらのスコープの対象外です）。
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

デフォルトのスコープ: Earth Engine コードエディタとクライアント ライブラリ（ee.Authenticate() など）の両方で構成されたデフォルトのスコープには、earthengine、cloud-platform、drive のすべてのスコープが含まれます（詳細は前述を参照）。したがって、権限の制限が必要な特定のセキュリティ制約または組織のポリシーがある場合にのみ、スコープのカスタマイズ（ee.Authenticate(scopes=[...]) で scopes パラメータを使用するなど）が必要です。

トラブルシューティング

Cloud プロジェクトを作成できない場合はどうすればよいですか？

組織によっては、Cloud プロジェクトを作成できるユーザーを制御しています。プロジェクトの作成時に Notebook Authenticator ページでエラーが発生した場合は、次のことを試してください。

1. プロジェクトを直接作成して、必要な権限があるかどうかを確認します。
2. プロジェクトを作成するために利用できるプロセスについては、組織の管理者にお問い合わせください。
3. 組織外のアカウントからプロジェクトを作成し、仕事で使用するアカウントをプロジェクトのオーナーとして追加します。注: 一部の組織には、外部プロジェクトからの OAuth クライアントへのアクセスを禁止するセキュリティ ポリシーがあります。

エラー: 「Earth Engine API has not been used in project XXX before or it is disabled」

まず、ee.Initialize() またはコマンドラインでプロジェクトを構成していることを確認します（Cloud と Colab で提供されるデフォルトのプロジェクトでは、Earth Engine が有効になっていません）。次に、プロジェクトで Earth Engine API が 有効になっていることを確認します。

エラー: 「プロジェクトに互換性のない OAuth2 クライアント構成があります」

クラウド プロジェクトに設定できる OAuth2 クライアント構成は 1 つだけです。Cloud プロジェクトに OAuth2 クライアント構成が設定されているかどうかを確認するには、[認証情報] ページの OAuth 2.0 クライアント ID を確認します。Notebook Authenticator によって互換性のある構成がすでに設定されている別のクラウド プロジェクトを選択するか、OAuth2 クライアントのないクラウド プロジェクトを選択または作成する必要があります。認証システムがこのプロジェクトを自動的に構成します。残念ながら、OAuth システムではユーザーが構成を削除できないため、別のプロジェクトを使用する必要があります。このプロジェクトは、他の Earth Engine 作業で使用されるプロジェクトと同じである必要はありません。このエラーは Colab モードでは発生しません。

エラー: 「gcloud failed. 上記のエラーを確認し、必要に応じて 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 の実行を試してください。

エラー: 「[Cloud Storage / BigQuery] の必須スコープがありません」

このエラーは、Earth Engine リクエストが Cloud Storage または BigQuery リソースにアクセスする際に、Earth Engine の初期化に使用された認証情報に、そのサービスに必要なスコープ（またはすべての Google Cloud サービスを網羅する cloud-platform スコープ）が含まれていない場合に発生します。これは通常、認証中に scopes パラメータをカスタマイズした場合（たとえば、ee.Authenticate(scopes=[...]) に Earth Engine スコープのみを指定した場合）、または既存の認証情報がこれらのスコープなしで作成された場合に発生します。

この問題を解決するには、次の 2 つの方法があります。

• デフォルトのスコープで再認証する: Earth Engine のデフォルト認証情報には、Cloud Storage と BigQuery の両方を含む cloud-platform スコープが含まれています。デフォルト設定を使用して再認証します。
  • Python の場合: ee.Authenticate(force=True)
  • コマンドラインの場合: earthengine authenticate --force
• 必要なスコープを含める: 環境でスコープのカスタマイズが必要な場合は、scopes リストに https://www.googleapis.com/auth/cloud-platform または特定のサービス スコープ（Cloud Storage の場合は https://www.googleapis.com/auth/devstorage.full_control または https://www.googleapis.com/auth/devstorage.read_only、BigQuery の場合は https://www.googleapis.com/auth/bigquery など）が含まれていることを確認します。

使用可能なスコープの詳細については、スコープの詳細をご覧ください。

技術メモ

技術的な詳細: これらのさまざまな認証情報作成メカニズムが必要になるのは、既知の信頼できる環境に認証情報を渡す必要があるためです。上記のさまざまなケースについて簡単に説明します。

• 以前は、トークンを取得してどこにでも貼り付けることができる paste モードがありましたが、リスクが高すぎると判断されたため、現在は使用できません。
• colab: auth.authenticate_user() を実行すると、ノートブック環境自体である「Colab」認証クライアントと認証情報を共有するように求められます。これらは google.auth.default() を介して利用可能になり、ee.Initialize() によって使用されます。
• localhost: 認証情報がブラウザからローカルマシンのポートに渡されます。この場合、エンドツーエンドのセキュリティは、ローカル マシンが侵害されていないという事実に基づいています。表示される認証クライアントは「Earth Engine Authenticator」です。
• gcloud: gcloud リファレンスで説明されている --launch-browser フローを使用します。リモート マシンの場合は --no-launch-browser を使用します。使用される認証クライアントは「Google Auth Library」です。
• notebook: 仕事専用の新しい認証クライアントを作成します。同意ページにメールアドレスが表示されます。このクライアントは「開発」モードに設定されています。これは、以前の貼り付けモードのトークンを許可する特殊なケースです。このようなクライアントは多数のユーザーと共有できないため、この場合は独自のプロジェクトを使用する必要があります。