公告：凡是在
2025 年 4 月 15 日前註冊使用 Earth Engine 的非商業專案，都必須
驗證非商業用途資格，才能繼續存取 Earth Engine。
ee.data.authenticateViaOauth
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
透過 Google API JavaScript 用戶端程式庫，設定 EE API 呼叫的用戶端驗證。如果頁面尚未載入程式庫，系統會自動載入。如果使用者先前未曾授予存取權，系統會要求使用者授予 clientId 所識別的應用程式存取 EE 資料的權限。
在呼叫 ee.initialize() 之前，應先呼叫這個或其他驗證方法。
請注意，如果使用者先前未授予用戶端 ID 所識別應用程式的存取權，系統預設會嘗試彈出對話方塊，提示使用者授予必要權限。不過，瀏覽器可能會封鎖這個彈出式視窗。為避免發生這種情況，請指定 opt_onImmediateFailed 回呼，並在其中算繪網頁內登入按鈕，然後從這個按鈕的點擊事件處理常式呼叫 ee.data.authenticateViaPopup()。這樣一來，瀏覽器就不會封鎖彈出式視窗，因為這是使用者動作的直接結果。
系統會盡可能自動重新整理驗證權杖。您可以放心，所有非同步呼叫都會傳送適當的憑證。不過，如果是同步呼叫，您應該使用 ee.data.getAuthToken() 檢查是否有驗證權杖，如果沒有，請手動呼叫 ee.data.refreshAuthToken()。權杖重新整理作業是非同步作業，無法在同步呼叫之前，根據需求在幕後執行。
| 用量 | 傳回 |
|---|
ee.data.authenticateViaOauth(clientId, success, error, extraScopes, onImmediateFailed, suppressDefaultScopes) | |
| 引數 | 類型 | 詳細資料 |
|---|
clientId | 字串 | 應用程式的 OAuth 用戶端 ID，或空值 (如要停用已驗證的呼叫)。您可以透過 Google Developers Console 取得這項資訊。專案必須具備與指令碼執行所在網域相應的 JavaScript 來源。 |
success | 函式 | 驗證成功時要呼叫的函式。 |
error | 函式 (選用) | 驗證失敗時要呼叫的函式，並傳遞錯誤訊息。如果立即 (幕後) 模式的驗證失敗，且指定了 opt_onImmediateFailed，系統會呼叫該函式，而非 opt_error。 |
extraScopes | List<String> (選用) | 要要求的額外 OAuth 範圍。 |
onImmediateFailed | 函式 (選用) | 如果自動幕後驗證失敗，要呼叫的函式。預設值為 ee.data.authenticateViaPopup()，會繫結至傳遞的回呼。 |
suppressDefaultScopes | 布林值 (選填) | 如果為 true，系統只會要求 opt_extraScopes 中指定的範圍；除非在 opt_extraScopes 中明確指定，否則不會要求預設範圍。 |
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-25 (世界標準時間)。
[null,null,["上次更新時間：2025-07-25 (世界標準時間)。"],[[["\u003cp\u003eEnables authenticated access to Earth Engine data using your Google account via the Google APIs Client Library for JavaScript.\u003c/p\u003e\n"],["\u003cp\u003eRequires initialization before using Earth Engine functionalities and might prompt users for permission to access their Earth Engine data.\u003c/p\u003e\n"],["\u003cp\u003eAutomatically refreshes authentication tokens for asynchronous calls, but synchronous calls may require manual token refresh using \u003ccode\u003eee.data.getAuthToken()\u003c/code\u003e and \u003ccode\u003eee.data.refreshAuthToken()\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eProvides options for handling authentication failures, including specifying custom error callbacks and displaying an in-page login button to avoid browser popup blockers.\u003c/p\u003e\n"],["\u003cp\u003eAllows customization of OAuth scopes and client ID for specific application requirements.\u003c/p\u003e\n"]]],[],null,["# ee.data.authenticateViaOauth\n\n\u003cbr /\u003e\n\nConfigures client-side authentication of EE API calls through the Google APIs Client Library for JavaScript. The library will be loaded automatically if it is not already loaded on the page. The user will be asked to grant the application identified by clientId access to their EE data if they have not done so previously.\n\n\u003cbr /\u003e\n\nThis or another authentication method should be called before ee.initialize().\n\nNote that if the user has not previously granted access to the application identified by the client ID, by default this will try to pop up a dialog window prompting the user to grant the required permission. However, this popup can be blocked by the browser. To avoid this, specify the opt_onImmediateFailed callback, and in it render an in-page login button, then call ee.data.authenticateViaPopup() from the click event handler of this button. This stops the browser from blocking the popup, as it is now the direct result of a user action.\n\nThe auth token will be refreshed automatically when possible. You can safely assume that all async calls will be sent with the appropriate credentials. For synchronous calls, however, you should check for an auth token with ee.data.getAuthToken() and call ee.data.refreshAuthToken() manually if there is none. The token refresh operation is asynchronous and cannot be performed behind-the-scenes on-demand prior to synchronous calls.\n\n| Usage | Returns |\n|------------------------------------------------------------------------------------------------------------------------------------|---------|\n| `ee.data.authenticateViaOauth(clientId, success, `*error* `, `*extraScopes* `, `*onImmediateFailed* `, `*suppressDefaultScopes*`)` | |\n\n| Argument | Type | Details |\n|-------------------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `clientId` | String | The application's OAuth client ID, or null to disable authenticated calls. This can be obtained through the Google Developers Console. The project must have a JavaScript origin that corresponds to the domain where the script is running. |\n| `success` | Function | The function to call if authentication succeeded. |\n| `error` | Function, optional | The function to call if authentication failed, passed the error message. If authentication in immediate (behind-the-scenes) mode fails and opt_onImmediateFailed is specified, that function is called instead of opt_error. |\n| `extraScopes` | List\\\u003cString\\\u003e, optional | Extra OAuth scopes to request. |\n| `onImmediateFailed` | Function, optional | The function to call if automatic behind-the-scenes authentication fails. Defaults to ee.data.authenticateViaPopup(), bound to the passed callbacks. |\n| `suppressDefaultScopes` | Boolean, optional | When true, only scopes specified in opt_extraScopes are requested; the default scopes are not requested unless explicitly specified in opt_extraScopes. |"]]
