Công cụ dòng lệnh

Công cụ earthengine là một chương trình tiện ích cho phép bạn quản lý các tài sản và tác vụ Earth Engine từ dòng lệnh. Thư viện này được cài đặt tự động khi bạn cài đặt API Python. Để kiểm tra xem công cụ này đã được cài đặt và hoạt động đúng cách hay chưa, hãy nhập nội dung sau vào dòng lệnh:

    earthengine

Nếu được cài đặt đúng cách, công cụ này sẽ in một bản tóm tắt ngắn về các lệnh có sẵn. Để được trợ giúp về một lệnh cụ thể, hãy sử dụng:

    earthengine command -h

Trong lần đầu tiên cài đặt API Python, bạn cần đăng nhập bằng lệnh authenticate được mô tả bên dưới. Các phần sau đây mô tả chi tiết hơn về các lệnh có sẵn.

Thông tin xác thực tài khoản dịch vụ

Để sử dụng CLI bằng thông tin xác thực của tài khoản dịch vụ, hãy sử dụng cờ service_account_file để trỏ đến tệp JSON chứa khoá của tài khoản dịch vụ.

    earthengine --service_account_file=service_account_creds.json

Cách sử dụng trong Colab

Công cụ dòng lệnh Earth Engine được cài đặt sẵn và sẵn sàng để sử dụng trong Google Colab.

Xác thực

Xác thực cho mỗi phiên Colab mới hoặc nếu máy ảo hết hạn do không hoạt động (thông tin xác thực không được lưu giữa các phiên).

Nhập thư viện ứng dụng Python và gọi ee.Authenticate() để kích hoạt quy trình xác thực. Làm theo lời nhắc để hoàn tất quy trình xác thực. auth_mode mặc định trong Colab là colab, hãy xem Hướng dẫn xác thực để biết các tuỳ chọn khác.

import ee
ee.Authenticate()

Thực thi lệnh

Để chạy các tiện ích dòng lệnh, chẳng hạn như Earth Engine CLI, bạn cần thêm dấu chấm than vào đầu lệnh gọi.

!earthengine -h

Đặt dự án trên Cloud

Sử dụng tuỳ chọn --project để đặt một dự án Cloud cho từng lệnh earthengine riêng lẻ.

!earthengine --project my-project <command>

Ngoài ra, hãy đặt một dự án mặc định để tất cả lệnh gọi earthengine sử dụng bằng lệnh set_project. Dự án sẽ được thêm vào tệp thông tin xác thực (~/.config/earthengine/credentials) và được dùng cho các lệnh tiếp theo, trừ phi bị ghi đè bằng tuỳ chọn --project. Đặt một dự án mặc định cho mỗi phiên Colab mới hoặc nếu máy ảo hết hạn do không hoạt động (thông tin xác thực không được lưu giữa các phiên).

!earthengine set_project my-project

Tài liệu tham khảo về lệnh

xác thực

Xác thực công cụ dòng lệnh và thư viện ứng dụng Python với Earth Engine. Ví dụ:

    earthengine authenticate

Earth Engine sử dụng giao thức OAuth 2.0 để xác thực ứng dụng khách. Lệnh xác thực earthengine sẽ nhắc bạn thực hiện quy trình xác thực bằng trình duyệt web.

Bạn sẽ cần cài đặt gcloud nếu sử dụng chế độ xác thực gcloud mặc định. Xem các chế độ xác thực khác có sẵn thông qua tham số auth_mode trong hướng dẫn xác thực.

acl

In hoặc cập nhật danh sách kiểm soát quyền truy cập (ACL) của một tài sản Earth Engine. ACL kiểm soát những người có thể đọc hoặc ghi vào một thành phần. Ví dụ:

    earthengine acl get projects/my-project/assets/asset_id
    earthengine acl set public projects/my-project/assets/asset_id
    earthengine acl ch -u [e-mail]:R projects/my-project/assets/asset_id

Lệnh con get sẽ in nội dung mô tả ACL ở định dạng JSON. Lệnh con set đặt một ACL được cung cấp trong một tệp có cùng định dạng JSON. Bạn có thể sao chép ACL từ một thành phần sang các thành phần khác bằng cách lưu đầu ra từ get và cung cấp đầu ra đó cho set.

Lệnh con set cũng chấp nhận hai tên ACL đặc biệt:

• private: Xoá quyền của tất cả mọi người ngoại trừ chủ sở hữu.
• public: Cấp quyền đọc cho tất cả người dùng.

Lệnh con ch cho phép bạn thực hiện các thay đổi riêng lẻ đối với ACL. Để cấp quyền đọc, hãy chỉ định -u [e-mail]:R, để cấp quyền ghi, hãy chỉ định -u [e-mail]:W và để xoá quyền của người dùng, hãy chỉ định -d [e-mail]. Bạn có thể sử dụng giá trị nhận dạng người dùng đặc biệt AllUsers để cấp hoặc thu hồi quyền đọc cho tất cả người dùng. (Lưu ý rằng việc thu hồi quyền AllUsers không thu hồi bất kỳ quyền bổ sung nào mà bạn cũng có thể đã cấp cho từng người dùng.)

thành phần

In hoặc cập nhật siêu dữ liệu liên kết với một tài sản Earth Engine. Ví dụ:

    earthengine asset info projects/my-project/assets/asset_id
    earthengine asset set -p name=value projects/my-project/assets/asset_id

Lệnh phụ info sẽ in thông tin chi tiết về tài sản, bao gồm cả siêu dữ liệu của tài sản đó, ở dạng JSON. Lệnh phụ set đặt các thuộc tính siêu dữ liệu riêng lẻ trên một thành phần.

Giá trị của các thuộc tính siêu dữ liệu mà bạn đặt có thể là số hoặc chuỗi. Khi đặt tên thuộc tính bằng cờ --property hoặc -p, hãy phân tách tên và giá trị thuộc tính bằng dấu bằng. Loại dữ liệu được phát hiện tự động hoặc bạn có thể chỉ định loại dữ liệu một cách rõ ràng bằng cách thêm tiền tố (string), (number) hoặc (date) vào tên thuộc tính. Ví dụ: mã này đặt một thuộc tính có giá trị chuỗi với giá trị "42":

    earthengine asset set -p '(string)name=42' projects/my-project/assets/asset_id

(Dấu ngoặc kép trong ví dụ này ngăn shell diễn giải dấu ngoặc đơn. Các tệp này có thể cần thiết hoặc không cần thiết, tuỳ thuộc vào shell và nền tảng của bạn.)

Để xoá một thuộc tính, hãy đặt thuộc tính đó thành null mà không có loại:

    earthengine asset set -p name=null projects/my-project/assets/asset_id

Thuộc tính ngày chỉ là các số đại diện cho số mili giây kể từ mốc thời gian Unix (tức là nửa đêm ngày 1 tháng 1 năm 1970) và có thể được chỉ định trực tiếp dưới dạng số hoặc theo một trong các định dạng sau:

    YYYY-MM-DD
    YYYY-MM-DDThh:mm:ss
    YYYY-MM-DDThh:mm:ss.f

Múi giờ được giả định là UTC. Bạn có thể đặt các thuộc tính thời gian bắt đầu và kết thúc đặc biệt bằng cách sử dụng cờ --time_start và --time_end:

    earthengine asset set --time_start 1978-10-15T12:34:56 projects/my-project/assets/asset_id

cp

Sao chép một thành phần. Ví dụ:

    earthengine cp projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

create

Tạo thư mục và bộ sưu tập hình ảnh mới. Ví dụ:

    earthengine create folder projects/my-project/assets/folder_id
    earthengine create collection projects/my-project/assets/collection_id

Sử dụng lệnh con folder để tạo thư mục và collection để tạo tuyển tập hình ảnh. Bạn có thể chỉ định tuỳ chọn -p để tạo đệ quy các thư mục mẹ nếu cần. Theo mặc định, các thư mục và hình ảnh mới tạo sẽ có ACL riêng tư.

ls

Liệt kê nội dung của một hoặc nhiều thư mục hoặc bộ sưu tập. Ví dụ:

    earthengine ls users/username

Tuỳ chọn -l yêu cầu định dạng dài với nhiều thông tin hơn về từng thành phần (hiện chỉ là loại thành phần). Bạn có thể chỉ định --max_items number (hoặc -m cho ngắn gọn) để giới hạn số lượng mục trong mỗi thư mục hoặc bộ sưu tập mà bạn liệt kê:

    earthengine ls -m 10 projects/my-project/assets/my_large_collection

Việc chạy lệnh ls mà không có đối số sẽ liệt kê các thư mục cấp cao nhất mà bạn sở hữu.

kiểu máy

Công cụ để thao tác với các mô hình đã lưu của TensorFlow.

model prepare

Chuẩn bị mô hình đã lưu để phân phát trong Earth Engine. Cụ thể, thao tác này sẽ chuyển đổi SavedModel thành một dạng phù hợp để xử lý các yêu cầu từ Earth Engine. (Tìm hiểu thêm về SavedModel.)

    earthengine model prepare my_source_dir my_dest_dir '{"Conv2D:0":"my_input_band"}' '{"Sigmoid:0":"my_output_band"}'

Tìm hiểu thêm về các mô hình trên Nền tảng AI tại đây. Xem ví dụ đầy đủ tại đây.

mv

Di chuyển hoặc đổi tên một thành phần. Ví dụ:

    earthengine mv projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

project_config

Xem trước: việc thiết lập cấu hình dự án là một tính năng Xem trước, vì vậy, các lệnh gọi phải bao gồm từ khoá alpha.

Đặt giá trị cấu hình dự án. Trước khi sử dụng lệnh này, hãy nhớ thiết lập một dự án bằng set_project.

get

Để xem cấu hình dự án, hãy sử dụng lệnh con get:

    earthengine alpha project_config get

Nếu bạn có quyền xem chế độ cài đặt tác vụ hàng loạt của dự án, thì kết quả sẽ chứa:

• maxConcurrentExports: một số cho biết số lượng tác vụ hàng loạt tối đa có thể chạy song song trên tất cả người dùng cho một dự án nhất định. Theo mặc định, giá trị này được đặt thành mức tối đa mà gói thuê bao của tài khoản thanh toán được liên kết cho phép.

Ngoài ra, nếu bạn có quyền xem cấu hình kế hoạch, thì kết quả sẽ chứa:

• planMaxConcurrentExports, một số cho biết số lượng tác vụ hàng loạt tối đa có thể chạy song song trên tất cả người dùng và dự án sử dụng tài khoản thanh toán.

đặt

Để cập nhật cấu hình của dự án, hãy sử dụng lệnh con set. Bạn có thể định cấu hình các chế độ cài đặt sau:

• max_concurrent_exports, để kiểm soát tính song song của tác vụ hàng loạt
  tối đa của dự án
  • yêu cầu quyền chính xác

Ví dụ: để định cấu hình một dự án chỉ cho phép 10 tác vụ chạy song song cho dự án đã cho:

    earthengine alpha project_config set --max_concurrent_exports=10

Kết quả hiển thị cấu hình dự án đã cập nhật, giống với kết quả mà get trả về.

Để biết thêm thông tin về tính năng song song tác vụ theo lô, hãy xem trang Hạn mức Earth Engine.

rm

Xoá một hoặc nhiều thành phần. Ví dụ:

    earthengine rm projects/my-project/assets/asset_id
    earthengine rm -r projects/my-project/assets/folder_id

Bạn có thể sử dụng cờ -r để xoá nội dung của một thư mục hoặc bộ sưu tập một cách đệ quy. Để đảm bảo an toàn khi xoá nhiều thành phần, bạn có thể sử dụng cờ --dry_run để xác minh chính xác những thành phần sẽ bị xoá mà không thực sự xoá bất kỳ thành phần nào.

set_project

Đặt dự án Google Cloud mà qua đó các yêu cầu tính toán được định tuyến.

    earthengine set_project foo-project

Bạn cần có lệnh này trước khi chạy các lệnh yêu cầu chức năng trên đám mây, chẳng hạn như model.

tác vụ

In thông tin về hoặc quản lý các tác vụ chạy trong thời gian dài. Ví dụ:

    earthengine task list
    earthengine task list -l
    earthengine task info TASK_ID
    earthengine task cancel TASK_ID

Lệnh phụ list liệt kê thông tin cơ bản về các tác vụ mà bạn đã gửi gần đây. Tuỳ chọn -l yêu cầu định dạng dài với nhiều thông tin hơn về từng tác vụ. Lệnh con info in thông tin chi tiết về từng tác vụ. Lệnh con cancel huỷ một hoặc nhiều tác vụ đang chạy.

tải lên

Tải hình ảnh hoặc bảng từ Google Cloud Storage lên Earth Engine hoặc tạo tài sản dựa trên hình ảnh bên ngoài.

hình ảnh

Cách tải thành phần hình ảnh lên bằng chế độ cài đặt mặc định:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id gs://bucket/image.tif

Nếu bạn chỉ định nhiều tệp hình ảnh đầu vào, các tệp đó sẽ được diễn giải dưới dạng thẻ thông tin của một thành phần hình ảnh. Bạn có thể tìm hiểu thêm về các tuỳ chọn tải hình ảnh lên Earth Engine trong phần Tải thành phần hình ảnh lên: Tuỳ chọn nâng cao.

Bạn có thể chỉ định chính sách giảm kim tự tháp bằng cách sử dụng cờ --pyramiding_policy. Bạn có thể đặt cờ này thành một trong các giá trị mean (mặc định), sample, mode, min hoặc max. Điều này sẽ kiểm soát cách Earth Engine tạo kim tự tháp của các phiên bản hình ảnh có độ phân giải thấp hơn:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --pyramiding_policy=sample gs://bucket/image.tif

Bạn có thể sử dụng --last_band_alpha để cho biết rằng mặt nạ cho hình ảnh phải được lấy từ kênh alpha trong dải cuối cùng:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --last_band_alpha gs://bucket/image.tif

Bạn có thể chỉ định giá trị không có dữ liệu bằng cách sử dụng cờ --nodata_value. Thao tác này sẽ che mọi pixel trong hình ảnh bằng giá trị đó:

    earthengine upload image --asset_id=users/myuser/asset --nodata_value=255 gs://bucket/image.tif

Bạn cũng có thể chỉ định các thuộc tính siêu dữ liệu để đặt trên thành phần bằng cách sử dụng cùng một cờ mà lệnh asset set mô tả ở trên chấp nhận. Các tuỳ chọn này cũng được mô tả trong hướng dẫn về Tệp kê khai hình ảnh.

bàn

Để tải tệp Shapefile, CSV hoặc TFRecord từ Google Cloud Storage lên một tài sản bảng Earth Engine, bạn có thể sử dụng bất kỳ phương thức nào sau đây:

    earthengine upload table --asset_id=projects/my-project/assets/myUploadedShapefile gs://bucket/foo.shp
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedCSV gs://bucket/foo.csv
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedTFRecord gs://bucket/foo.tfrecord

Lưu ý: khi tải tệp Shapefile lên, bạn chỉ cần chỉ định đường dẫn đến tệp .shp. Các tệp .dbf, .shx và .prj liên quan phải nằm ở cùng một vị trí. Ngoài ra, bạn có thể chỉ định một tệp .zip chứa các tệp cần thiết.

Có nhiều tuỳ chọn liên quan đến cách diễn giải tệp CSV và TFRecord. Bạn có thể xem danh sách đầy đủ các tuỳ chọn tải bảng lên bằng cách truy cập vào hướng dẫn về Tệp kê khai bảng hoặc bằng:

    earthengine upload table -h

external_image

Xem trước: Tính năng Xem trước là tạo một thành phần được hỗ trợ bằng hình ảnh bên ngoài, vì vậy, các lệnh gọi phải bao gồm từ khoá alpha.

Để tạo một thành phần được hỗ trợ bằng hình ảnh bên ngoài, hãy chạy lệnh upload_image bằng tệp kê khai:

earthengine alpha upload external_image --manifest /tmp/foo.json

Ví dụ về tệp kê khai:

{
  "name": "projects/{project}/assets/cogdemo1",
  "tilesets": [
    { "id": "0", "sources": [{ "uris": ["gs://ee-docs-demos/COG_demo.tif"] }] }
  ],
  "properties": {
    "source": "https://code.earthengine.google.com/d541cf8b268b2f9d8f834c255698201d"
  },
  "startTime": "2016-01-01T00:00:00.000000000Z",
  "endTime": "2016-12-31T15:01:23.000000000Z"
}

Hãy xem hướng dẫn về Cloud GeoTIFF và hướng dẫn về Tệp kê khai hình ảnh để biết thêm thông tin chi tiết về cách tạo tệp kê khai.