Thông báo: Tất cả dự án phi thương mại đã đăng ký sử dụng Earth Engine trước ngày 15 tháng 4 năm 2025 phải xác minh điều kiện sử dụng phi thương mại để duy trì quyền truy cập vào Earth Engine.

Trang này được dịch bởi Cloud Translation API.

Xác thực và khởi chạy

Trước khi có thể gửi yêu cầu đến Earth Engine thông qua một thư viện ứng dụng, bạn phải xác thực và sử dụng thông tin xác thực thu được để khởi chạy ứng dụng Earth Engine.

Trình soạn thảo mã Earth Engine và JavaScript

Quy trình xác thực và khởi chạy được xử lý tự động trong Trình soạn thảo mã. Bạn có thể chọn định tuyến các yêu cầu thông qua một Dự án trên đám mây từ thông tin đăng nhập của bạn ở góc trên bên phải của Trình chỉnh sửa mã.

Nếu bạn đang sử dụng API JavaScript (bên ngoài Trình soạn thảo mã), hãy sử dụng một trong các trình trợ giúp xác thực trong ee.data (ví dụ: ee.data.authenticateViaPopup()) theo sau là ee.initialize() như trong ví dụ này.

Python và Dòng lệnh

Trước khi sử dụng thư viện ứng dụng Earth Engine Python, bạn cần xác thực (xác minh danh tính) và sử dụng thông tin xác thực thu được để khởi chạy ứng dụng Python. Các luồng xác thực sử dụng Dự án trên đám mây để xác thực và được dùng cho mục đích sử dụng không trả phí (miễn phí, phi thương mại) cũng như sử dụng có tính phí. Để xác thực và khởi chạy, hãy chạy

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

Trước tiên, thao tác này sẽ chọn chế độ xác thực phù hợp nhất với môi trường của bạn và nhắc bạn xác nhận quyền truy cập cho các tập lệnh. Nếu đã có thông tin xác thực, hệ thống sẽ tự động sử dụng lại thông tin đó – hãy chạy ee.Authenticate(force=True) để tạo thông tin xác thực mới.

Bước khởi chạy xác minh rằng có thông tin xác thực hợp lệ, được tạo từ ee.Authenticate() hoặc tồn tại trước đó dưới dạng thông tin xác thực mặc định của Google. Sau đó, thư viện này khởi chạy thư viện ứng dụng Python bằng các phương thức mà máy chủ phụ trợ hỗ trợ. Bạn cần cung cấp một dự án mà bạn sở hữu hoặc có quyền sử dụng. Hãy xem phần Thiết lập dự án trên Google Cloud để đăng ký dự án và bật API Earth Engine. Dự án này sẽ được dùng để chạy tất cả các thao tác trên Earth Engine.

Trên dòng lệnh, lệnh gọi tương đương là earthengine authenticate. Nếu thông tin xác thực đã hết hạn hoặc không hợp lệ, bạn có thể cần chạy earthengine authenticate --force. Lệnh gọi dòng lệnh sẽ khởi chạy trên mỗi lệnh gọi và bạn có thể sử dụng đối số --project để thiết lập dự án.

Bạn cũng có thể định cấu hình một dự án cho tất cả các lệnh gọi trong tương lai bằng cách chạy earthengine set_project {my-project}. Dòng lệnh và ee.Initialize() sẽ sử dụng giá trị này bất cứ khi nào một dự án không được chỉ định trực tiếp. Nếu sử dụng phương thức xác thực thông qua gcloud (xem bên dưới), thì dự án do gcloud auth application-default set-quota-project {my-project} đặt sẽ được dùng làm trường hợp cuối cùng.

Thông tin xác thực

Mục đích của quy trình xác thực Earth Engine là lấy "mã thông báo" bảo mật từ tài khoản đã đăng nhập của bạn. Mã này có thể được lưu trữ để cấp cho tập lệnh quyền truy cập vào dữ liệu của bạn. Vì lý do bảo mật, hệ thống xác thực của Google chỉ truyền các mã thông báo đó đến những hệ thống có thể được bảo mật – hãy xem các ghi chú kỹ thuật bên dưới.

Do tính nhạy cảm của loại hệ thống liên quan, có nhiều cách để tiếp tục tuỳ thuộc vào trường hợp cụ thể của bạn. Hầu hết các tuỳ chọn đều được kiểm soát bằng tham số auth_mode: dưới dạng ee.Authenticate(auth_mode=...) hoặc earthengine authenticate --auth_mode=... trên dòng lệnh.

Xin lưu ý rằng nếu thông tin xác thực của Google đã tồn tại trong môi trường của bạn, thì bạn có thể không cần gọi ee.Authenticate(). Máy ảo Google Cloud, App Engine và các môi trường khác cung cấp "thông tin xác thực môi trường xung quanh" có thể sử dụng và gcloud auth application-default login cũng sẽ tạo các thông tin xác thực đó.

Tuy nhiên, bạn nên sử dụng ee.Authenticate() ở đầu tất cả các tập lệnh để tăng tối đa khả năng tương thích. Không có thông số auth_mode, tính năng này được thiết kế để hoạt động trong hầu hết các trường hợp, nhưng hãy làm theo thông tin chi tiết bên dưới nếu chế độ mặc định không hoạt động. Chế độ mặc định được chọn như sau:

colab nếu chạy trong sổ tay Google Colab
notebook nếu chạy trong các sổ tay Jupyter không phải Colab khác
localhost nếu phát hiện thấy trình duyệt web và không cài đặt tệp nhị phân gcloud
gcloud, nếu không. Đối với chế độ này, bạn cần cài đặt gcloud.

Bảng và hướng dẫn tham khảo nhanh

Hướng dẫn quyết định này trình bày các tuỳ chọn có thể có nếu chế độ mặc định do ee.Authenticate() chọn không hoạt động. Ví dụ: nếu đang chạy trong các môi trường máy tính xách tay khác, bạn có thể phải chỉ định rõ notebook.

Môi trường cục bộ.
- "Cục bộ" có nghĩa là bạn đang chạy mã trong một màn hình shell Python hoặc sổ tay Python trên máy đang dùng – hoặc chính xác hơn là trên cùng một máy mà trình duyệt web của bạn đang chạy. Điều này bao gồm cả các trường hợp máy tính từ xa, trong đó cả Python và trình duyệt đều nằm trên cùng một máy (từ xa).
- Việc sử dụng auth_mode=localhost là dễ dàng nhất và sẽ được chọn theo mặc định nếu bạn chưa cài đặt gcloud, nhưng tập lệnh của bạn sẽ chỉ hoạt động trong môi trường cục bộ.
- Cả auth_mode=gcloud và auth_mode=notebook đều có sẵn.
Môi trường từ xa.
- "Từ xa" có nghĩa là trình duyệt của bạn đang ở trên một máy (máy cục bộ) nhưng mã của bạn đang chạy ở nơi khác, chẳng hạn như trên một máy trạm từ xa hoặc máy tính xách tay dựa trên web.
- Nếu trong Colab, hãy sử dụng auth_mode=colab; hoặc sử dụng gcloud nếu bạn cần đặt scopes để gọi các API khác.
- Nếu bạn có thể cài đặt gcloud trên cả máy từ xa và máy cục bộ, hãy sử dụng auth_mode=gcloud.
- Nếu bạn có thể sử dụng dự án xác thực (xem bên dưới), hãy sử dụng auth_mode=notebook.
- Nếu không, nếu bạn không thể sử dụng dự án hoặc cài đặt gcloud hoặc sử dụng Colab hoặc sử dụng trình duyệt trên cùng một máy:
- (Tiếp tục) trao đổi với quản trị viên về việc tạo dự án. Ví dụ:
  - Yêu cầu quản trị viên định cấu hình dự án cho bạn (với vai trò là Chủ sở hữu hoặc Người chỉnh sửa hoặc Người chỉnh sửa cấu hình OAuth)
  - Hoặc yêu cầu quản trị viên cấp cho bạn quyền tạo dự án.

Bảng này cho biết tổ hợp tính năng nào được hỗ trợ theo từng chế độ.

	Đối với máy tính cục bộ hay từ xa?	Cần có dự án	Phạm vi có thể đặt	Cần có CLI cục bộ	Chủ sở hữu dự án
`localhost`	local	Có	Có	Không	Không
`colab`	từ xa	Có	Không	Không	Không
`gcloud`	cả hai	Có	Có	Không	Không
`notebook`	cả hai	Có	Có	Không	Có

Thông tin xác thực cho Tài khoản dịch vụ và Compute Engine

ee.Initialize() sẽ sử dụng thông tin xác thực Earth Engine (ee.Authenticate() lưu trữ trong ~/.config/earthengine/credentials) hoặc truy xuất thông tin xác thực từ google.auth.default(), nhưng nếu cần, bạn có thể truyền đối số credentials= để sử dụng thông tin xác thực từ nơi khác, bỏ qua các thông tin xác thực mặc định này.

Nếu đang xác thực mã Python sẽ chạy mà không cần giám sát, bạn nên xác thực bằng tài khoản dịch vụ thay vì tài khoản người dùng. Hãy xem các tài liệu này để biết cách sử dụng tài khoản dịch vụ với Earth Engine. Các phương thức khác bao gồm authenticate_service_account trong mô-đun xác thực Colab và các phương thức được mô tả trong Hướng dẫn xác thực dưới dạng tài khoản dịch vụ trên Google Cloud.

Nếu mã của bạn đang chạy trên một máy ảo Compute Engine, thì một tài khoản dịch vụ mặc định sẽ được tạo cho môi trường mà ee.Initialize() sẽ sử dụng theo mặc định. Bạn có thể cần phải đăng ký tài khoản dịch vụ để sử dụng Earth Engine nếu Dự án trên Google Cloud mà bạn dùng để khởi động máy ảo chưa được đăng ký để sử dụng Earth Engine (dùng cho mục đích thương mại hoặc phi thương mại).

Thông tin chi tiết về chế độ

auth_mode=colab. ee.Authenticate() sẽ tạo hoặc lấy thông tin xác thực mặc định mà Colab hỗ trợ bằng cách chạy colab.auth.authenticate_user() nếu cần. Thông tin xác thực luôn sử dụng phạm vi cloud-platform và cũng có thể được dùng để gọi các API đám mây khác.

auth_mode=gcloud. Thao tác này uỷ quyền xác thực cho công cụ gcloud và giống như việc chạy gcloud auth application-default login với các phạm vi Earth Engine mặc định (earthengine, cloud-platform và drive) hoặc các phạm vi trong đối số scopes. Chế độ gcloud hoạt động trong cả trường hợp cục bộ và từ xa.

Hướng dẫn từng bước cho chế độ gcloud (trường hợp cục bộ và từ xa)

Xác minh rằng gcloud đã được cài đặt trên máy cục bộ.
- Trong một thiết bị đầu cuối, hãy chạy gcloud help. Nếu bạn chưa cài đặt gcloud, hãy làm theo hướng dẫn này để cài đặt gcloud.
Dòng lệnh trên máy cục bộ
- Trong một thiết bị đầu cuối, hãy chạy earthengine authenticate.
- Kết quả của lệnh sẽ cho biết rằng gcloud đang được dùng để tìm nạp thông tin xác thực.
- Một cửa sổ trình duyệt sẽ mở ra trang chọn tài khoản. Nếu trình duyệt không tự động mở, hãy nhấp vào URL.
Trình duyệt: Lựa chọn tài khoản
- Chọn tài khoản bạn muốn dùng để xác thực.
Trình duyệt: Màn hình đồng ý
- Cho biết liệu bạn có sẵn sàng cấp các phạm vi được yêu cầu hay không rồi nhấp vào "Cho phép".
Trình duyệt: Màn hình xác nhận
- Trình duyệt sẽ hiển thị một trang xác nhận rằng bạn đã được xác thực và lệnh earthengine authenticate trong cửa sổ dòng lệnh sẽ báo cáo "Đã lưu thành công mã thông báo uỷ quyền".
- Trong một số trường hợp từ xa, trang web sẽ cung cấp cho bạn một mã để dán lại vào môi trường Python.
Tiếp tục khởi chạy.

auth_mode=localhost. Đây là quy trình tương tự như gcloud trong trường hợp bạn chưa cài đặt gcloud. Công cụ này thực hiện các bước tương tự như gcloud, nhưng chỉ hoạt động trong trường hợp cục bộ. Bạn có thể cung cấp số cổng Internet không bắt buộc, ví dụ: localhost:8086 hoặc sử dụng localhost:0 để tự động chọn cổng. Cổng mặc định là 8085.

auth_mode=notebook. Đây là chế độ đa năng được thiết kế để hoạt động trong các tình huống từ xa không có dòng lệnh cục bộ. Thao tác này sẽ đưa bạn đến trang Trình xác thực cho máy tính xách tay. Tại đây, bạn cần chọn hoặc tạo "dự án xác thực" – xem thông tin chi tiết và hướng dẫn khắc phục sự cố bên dưới. Dự án được truyền đến ee.Initialize() không nhất thiết phải khớp với dự án này – bạn có thể giữ nguyên dự án để xác thực trong khi làm việc trong nhiều dự án trên nhiều sổ tay. Bạn nên truyền một dự án một cách rõ ràng đến ee.Initialize(), nhưng dự án xác thực sẽ được sử dụng theo mặc định.

Hướng dẫn từng bước về chế độ máy tính xách tay

Trình duyệt: Sổ tay
1. Trong một ô mã của sổ tay, hãy chạy mã sau để bắt đầu quy trình xác thực bằng chế độ "sổ tay".
```
import ee
ee.Authenticate()
```
  Nhấp vào đường liên kết trong kết quả của ô để mở trang Trình xác thực cho máy tính xách tay trong một thẻ mới.
Trình duyệt: Trình xác thực Notebook
1. Xác minh rằng tài khoản người dùng chính xác đã được liệt kê.
2. Chọn một Dự án Google Cloud để dùng cho tính năng Xác thực. Nếu cần tạo một dự án mới, bạn nên sử dụng quy ước đặt tên "ee-xyz", trong đó xyz là tên người dùng Earth Engine thông thường của bạn. (Nếu bạn không thể chọn hoặc tạo Dự án trên đám mây, hãy xem phần khắc phục sự cố bên dưới.)
3. Nhấp vào Tạo mã thông báo.
Trình duyệt: Lựa chọn tài khoản
- Bạn sẽ thấy một trang chọn tài khoản. Nhấp vào tài khoản người dùng mà bạn muốn cấp quyền truy cập từ sổ tay.
Trình duyệt: Trang cảnh báo
- Một trang cảnh báo sẽ xuất hiện, cho biết rằng Google không tạo ứng dụng này (tức là mã trong sổ tay). Nhấp vào Tiếp tục để xác nhận.
Trình duyệt: Màn hình đồng ý
- Cho biết liệu bạn có sẵn sàng cấp các phạm vi được yêu cầu hay không rồi nhấp vào Tiếp tục.
Trình duyệt: Màn hình mã uỷ quyền
- Sao chép mã xác minh uỷ quyền
Trình duyệt: Sổ tay
- Chuyển về thẻ sổ tay rồi dán mã xác minh vào kết quả của ô sổ tay.
- Kết quả của ô sẽ cho biết "Đã lưu thành công mã thông báo uỷ quyền".
Tiếp tục khởi chạy.

Chế độ sổ tay có một tham số quiet hiếm khi được sử dụng: nếu được đặt, chế độ này sẽ chạy "không tương tác" và không nhắc cũng như không chờ bạn nhập mã xác thực. Thay vào đó, trình soạn thảo sẽ đưa ra một lệnh để chạy nhằm lưu mã.

Dự án xác thực

Bạn cần phải là Chủ sở hữu, Người chỉnh sửa hoặc Người chỉnh sửa cấu hình OAuth trên dự án xác thực được sử dụng ở chế độ sổ tay. Trong nhiều trường hợp, đặc biệt là trong các nhóm nhỏ, dự án xác thực mà bạn sử dụng trên trang Trình xác thực trên máy tính xách tay có thể giống với dự án chính mà bạn sử dụng cho công việc khác.

Do các vấn đề về bảo mật, "cấu hình ứng dụng khách OAuth" trên dự án xác thực là một chế độ thiết lập một lần. Nếu bạn hoặc người dùng khác đã thiết lập ứng dụng OAuth trên dự án vì lý do khác, thì bạn sẽ không thể xoá ứng dụng đó và sẽ thấy lỗi "cấu hình ứng dụng OAuth2 không tương thích". Bạn sẽ cần sử dụng một dự án khác để xác thực hoặc sử dụng các chế độ colab, localhost hoặc gcloud ở trên.

Khắc phục sự cố

Nếu tôi không thể tạo Dự án trên Cloud thì sao?

Một số tổ chức kiểm soát những người có thể tạo Dự án trên Google Cloud. Nếu bạn gặp lỗi trên trang Trình xác thực cho Notebook khi cố gắng tạo dự án, hãy thử một số cách sau:

Hãy thử tạo một dự án trực tiếp để xác nhận xem bạn có các quyền cần thiết hay không.
Hãy trao đổi với quản trị viên của tổ chức để tìm hiểu các quy trình tạo dự án.
Tạo dự án từ một tài khoản không phải tài khoản tổ chức và thêm tài khoản bạn sử dụng cho công việc làm Chủ sở hữu dự án. Lưu ý: một số tổ chức có chính sách bảo mật ngăn chặn quyền truy cập vào ứng dụng OAuth từ các dự án bên ngoài.

Lỗi: "Earth Engine API chưa được sử dụng trong dự án XXX trước đây hoặc API này bị tắt"

Trước tiên, hãy đảm bảo rằng bạn đã định cấu hình một dự án trong ee.Initialize() hoặc trên dòng lệnh (các dự án mặc định do Cloud và Colab cung cấp sẽ không bật Earth Engine). Thứ hai, hãy đảm bảo rằng bạn đã bật Earth Engine API trên dự án của mình.

Lỗi: "Dự án có cấu hình ứng dụng OAuth2 không tương thích"

Dự án trên đám mây chỉ có thể có một cấu hình Ứng dụng khách OAuth2. Bạn có thể kiểm tra xem một dự án trên đám mây có được thiết lập cấu hình Ứng dụng khách OAuth2 hay không bằng cách kiểm tra Mã ứng dụng OAuth 2.0 trên trang Thông tin xác thực. Bạn cần chọn một dự án Cloud khác có cấu hình tương thích đã được Trình xác thực cho máy tính xách tay thiết lập, hoặc chọn hoặc tạo một dự án Cloud không có ứng dụng OAuth2. Trình xác thực sẽ tự động định cấu hình dự án này. Rất tiếc, hệ thống OAuth không cho phép người dùng xoá cấu hình, vì vậy, người dùng phải sử dụng một dự án khác. Dự án này không nhất thiết phải là dự án được dùng cho công việc khác trên Earth Engine. Xin lưu ý rằng lỗi này không xảy ra trong chế độ Colab.

Lỗi: "gcloud không thành công. Vui lòng kiểm tra xem có lỗi nào ở trên không và cài đặt gcloud nếu cần."

Lỗi này có thể xảy ra nếu bạn chưa cài đặt gcloud hoặc gcloud không có trong PATH. Lỗi này cũng có thể xảy ra nếu bạn gọi ee.Authenticate(auth_mode='gcloud') từ trong một ô mã của sổ tay. Thay vào đó, hãy sử dụng ee.Authenticate(). Phương thức này sẽ mặc định sử dụng phương thức xác thực chế độ máy tính xách tay. Nếu bạn không thể tạo dự án, hãy xem giải pháp ở trên.

Nếu tôi không có quyền truy cập vào máy cục bộ để cài đặt gcloud thì sao?

Nếu đang làm việc trong môi trường chỉ dành cho web mà không có quyền truy cập vào thiết bị đầu cuối cục bộ và vẫn cần sử dụng thiết bị đầu cuối từ xa, bạn vẫn có thể khởi chạy công cụ dòng lệnh bằng cách kích hoạt chế độ sổ tay bằng cách chạy lệnh earthengine authenticate --auth_mode=notebook.

Lỗi 400: redirect_uri_mismatch

Bạn có thể gặp lỗi này nếu xác thực trên một máy từ xa mà không có quyền truy cập vào trình duyệt web. Hãy thử thêm --quiet nếu chạy earthengine authenticate từ dòng lệnh hoặc ee.Authenticate(quiet=True) nếu sử dụng ứng dụng Python. Bạn sẽ phải xác thực bằng gcloud từ một máy có quyền truy cập vào trình duyệt web.

Lỗi: "Ứng dụng của bạn đang xác thực bằng cách sử dụng Thông tin xác thực mặc định của ứng dụng cục bộ. API earthengine.googleapis.com yêu cầu một dự án hạn mức, nhưng dự án này không được đặt theo mặc định."

Lỗi này có thể xảy ra khi Earth Engine không xác định được mã dự án của bạn. Nếu các tuỳ chọn khắc phục sự cố của Google Cloud không hoạt động, hãy thử chạy earthengine set_project YOUR_PROJECT_ID hoặc gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Ghi chú kỹ thuật

Đối với những người tò mò về kỹ thuật: nhu cầu sử dụng các cơ chế tạo thông tin xác thực khác nhau này xuất phát từ nhu cầu truyền thông tin xác thực đến một môi trường đã biết và đáng tin cậy. Dưới đây là nội dung thảo luận nhanh về các trường hợp ở trên.

Trước đây, có một chế độ paste cung cấp cho bạn một mã thông báo để dán ở bất cứ đâu. Tuy nhiên, chế độ này được coi là quá rủi ro và không còn được cung cấp nữa.
colab: auth.authenticate_user() sẽ nhắc bạn chia sẻ thông tin xác thực với ứng dụng xác thực "Colab", chính môi trường sổ tay. Sau đó, các giá trị này sẽ có sẵn thông qua google.auth.default() và được ee.Initialize() sử dụng.
localhost: thông tin xác thực được truyền từ trình duyệt đến một cổng trên máy cục bộ. Trong trường hợp này, tính bảo mật toàn diện phụ thuộc vào việc máy cục bộ của bạn không bị xâm phạm. Ứng dụng xác thực mà bạn sẽ thấy là "Trình xác thực Earth Engine".
gcloud: Thao tác này sử dụng quy trình --launch-browser được mô tả trong tài liệu tham khảo gcloud và --no-launch-browser nếu trên máy từ xa. Ứng dụng xác thực được sử dụng là "Thư viện xác thực của Google".
notebook: Chúng tôi tạo một ứng dụng xác thực mới dành riêng cho công việc của bạn – bạn sẽ thấy địa chỉ email của mình trên trang đồng ý. Ứng dụng này được đặt ở chế độ "phát triển", đây là một trường hợp đặc biệt cho phép các mã thông báo chế độ dán cũ. Chúng ta cần sử dụng dự án của riêng bạn cho việc này vì không thể chia sẻ các ứng dụng đó với nhiều người dùng.