認証と初期化

クライアント ライブラリを介して Earth Engine にリクエストを送信する前に、認証を行い、生成された認証情報を使用して Earth Engine クライアントを初期化する必要があります。

Earth Engine コードエディタと JavaScript

認証と初期化は、コードエディタで自動的に処理されます。コードエディタの右上にあるログインから、Cloud プロジェクトを介してリクエストをルーティングすることもできます。

JavaScript API を使用している場合（コードエディタの外部）は、ee.data の認証ヘルパーのいずれか（ee.data.authenticateViaPopup() など）を使用し、この例に示すように ee.initialize() を使用します。

Python とコマンドライン

Earth Engine Python クライアント ライブラリを使用する前に、認証（本人確認）を行い、生成された認証情報を使用して 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 パラメータがない場合、ほとんどの状況で動作するように設計されていますが、デフォルト モードが動作しない場合は、以下の詳細に沿って操作してください。デフォルトのモードは次のように選択されます。

• colab（Google Colab ノートブックで実行する場合）
• notebook（Colab 以外の Jupyter ノートブックで実行する場合）
• localhost（ウェブブラウザが検出され、gcloud バイナリがインストールされていない場合）
• それ以外の場合は 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 構成編集者として）
    • または、プロジェクトを作成する権限を付与するよう管理者に依頼してください。

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

	ローカルまたはリモート	プロジェクトが必要	設定可能なスコープ	ローカル 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 の起動に使用したクラウド プロジェクトが 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 モードの手順ガイド（ローカルとリモートのケース）

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

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. ノートブックのコードセルで次のコードを実行して、「ノートブック」モードで認証フローを開始します。

      import ee
      ee.Authenticate()

      セル出力のリンクをクリックして、新しいタブで Notebook Authenticator ページを開きます。
2. ブラウザ: Notebook Authenticator
   1. 正しいユーザー アカウントが表示されていることを確認します。
   2. 認証に使用する Google Cloud プロジェクトを選択します。新しいプロジェクトを作成する必要がある場合は、命名規則「ee-xyz」を使用することをおすすめします。ここで、xyz は通常の Earth Engine ユーザー名です。（Cloud プロジェクトを選択または作成できない場合は、下記のトラブルシューティングのセクションをご覧ください）。
   認証に十分な IAM 権限が割り当てられている必要があります。たとえば、プロジェクトのオーナーまたは編集者、または割り当てられている他の IAM ロールに加えて、追加の「OAuth 構成編集者」事前定義ロールが必要です。チームの他のメンバーがこのプロジェクトで認証構成をすでに作成している場合は、追加の警告が表示されます。作成者が信頼できる共同編集者である場合にのみ、続行してください。
   3. [Generate Token] をクリックします。
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 Optimized GeoTIFF（COG）の読み込みやタスク出力のエクスポートなど）:
  • 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（Google Cloud サービスへの幅広いアクセス。Earth Engine、Cloud Storage、BigQuery が含まれます。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 プロジェクトを作成できない場合はどうすればよいですか？

組織によっては、クラウド プロジェクトを作成できるユーザーを制限している場合があります。プロジェクトの作成時に 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 クライアント構成があります」

Cloud プロジェクトに設定できる 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 パラメータをカスタマイズした場合（たとえば、Earth Engine スコープのみを ee.Authenticate(scopes=[...]) に指定した場合）や、既存の認証情報がこれらのスコープなしで作成された場合に発生します。

この問題を解決するには、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: お客様の作業専用の新しい認証クライアントを作成します。同意ページにお客様のメールアドレスが表示されます。このクライアントは「開発」モードに設定されています。これは、古い貼り付けモードのトークンを許可する特殊なケースです。このようなクライアントは多数のユーザーと共有できないため、この目的には独自のプロジェクトを使用する必要があります。