公告：凡是在
2025 年 4 月 15 日前註冊使用 Earth Engine 的非商業專案，都必須
驗證非商業用途資格，才能繼續存取 Earth Engine。
Method: projects.assets.getPixels
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
從圖片素材資源擷取像素。這個自訂方法可讓呼叫端要求圖片的任意像素圖塊，並可選擇指定頻帶和地圖投影。經過遮蓋或缺少的資料會編碼為零。
每項要求的未壓縮資料大小上限為 48 MB，計算方式為要求的像素尺寸、要求的圖像頻帶數量，以及每個頻帶的位元組數相乘。要求的大小也受到限制，每個維度的像素不得超過 32K，頻帶不得超過 1024 個。如果要求超出這些限制，就會傳回 400 (BAD_REQUEST) 錯誤代碼。
如果成功，回應主體會包含要求的像素資料，並以要求中 fileFormat 欄位指定的編碼方式呈現。
HTTP 要求
POST https://earthengine.googleapis.com/v1alpha/{name=projects/*/assets/**}:getPixels
這個網址使用 gRPC 轉碼語法。
路徑參數
| 參數 |
name |
string
必要欄位。要取得像素的圖片素材資源名稱。name 的格式為「projects/*/assets/**」(例如「projects/earthengine-legacy/assets/users/[USER]/[ASSET]」)。所有使用者擁有的素材資源都屬於「earthengine-legacy」專案 (例如「projects/earthengine-legacy/assets/users/foo/bar」)。所有其他素材資源都屬於「earthengine-public」專案 (例如"projects/earthengine-public/assets/LANDSAT").
授權需要指定資源 name 的下列 IAM 權限：
|
要求主體
要求主體的資料會採用以下結構：
| 欄位 |
fileFormat |
enum (ImageFileFormat)
用來傳回像素值的輸出檔案格式。
|
grid |
object (PixelGrid)
描述擷取資料所用的像素格線的參數。預設為資料的原生像素格線。
|
region |
object (Struct format)
如果有指定，則為要傳回的資料區域，以 GeoJSON 幾何物件指定 (請參閱 RFC 7946)。由於傳回的圖片一律為矩形，因此實際上會使用輸出座標系統中指定幾何圖形的邊界框架。如果同時指定了 grid.dimensions，則網格最終會重新調整為要求的大小。
|
bandIds[] |
string
如果存在，則指定要從中取得像素的特定頻帶組合。頻帶會透過 ID 識別，如 ImageBand 原型檔的 id 欄位所示。
|
visualizationOptions |
object (VisualizationOptions)
如果存在，則是一系列視覺化選項，可用於產生資料的 8 位元 RGB 視覺化，而非傳回原始資料。
|
workloadTag |
string
使用者提供的用於追蹤這項運算的代碼。
|
回應主體
如果成功，回應會是一般 HTTP 回應，其格式由方法定義。
授權範圍
需要下列其中一種 OAuth 範圍：
https://www.googleapis.com/auth/earthengine
https://www.googleapis.com/auth/earthengine.readonly
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/cloud-platform.read-only
詳情請參閱 OAuth 2.0 Overview。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-25 (世界標準時間)。
[null,null,["上次更新時間：2025-07-25 (世界標準時間)。"],[[["\u003cp\u003eFetches pixel data from Earth Engine image assets, allowing users to specify desired regions, bands, and output formats.\u003c/p\u003e\n"],["\u003cp\u003eRequests are limited to 48MB of uncompressed data, 32K pixels in each dimension, and 1024 bands; exceeding these limits will result in a 400 error.\u003c/p\u003e\n"],["\u003cp\u003eSuccessful responses contain the requested pixel data in the specified file format, or an 8-bit RGB visualization if visualization options are provided.\u003c/p\u003e\n"],["\u003cp\u003eThe request must specify the image asset name and can optionally include parameters for the output format, pixel grid, region, bands, visualization options, and a workload tag for tracking.\u003c/p\u003e\n"],["\u003cp\u003eAuthorization requires appropriate IAM permissions or one of the specified OAuth scopes, including 'earthengine', 'earthengine.readonly', 'cloud-platform', or 'cloud-platform.read-only'.\u003c/p\u003e\n"]]],[],null,["# Method: projects.assets.getPixels\n\nFetches pixels from an image asset. This custom method allows the caller to request an arbitrary tile of pixels from an image, optionally specifying the bands and map projection. Masked or missing data will be encoded as zeroes.\n\nRequests are limited to 48MB in uncompressed data per request, computed as the product of the request dimensions in pixels, the number of image bands requested, and the number of bytes per pixel for each band. Requests are also limited to at most 32K pixels in either dimension and at most 1024 bands. Requests exceeding these limits will result in an error code of 400 (BAD_REQUEST).\n\nIf successful, the response body contains the requested pixel data in the encoding specified in the `fileFormat` field of the request.\n\n### HTTP request\n\n`POST https://earthengine.googleapis.com/v1alpha/{name=projects/*/assets/**}:getPixels`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n| Parameters ||\n|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `name` | `string` Required. The name of the image asset from which to get pixels. `name` is of the format \"projects/\\*/assets/\\*\\*\" (e.g., \"projects/earthengine-legacy/assets/users/\\[USER\\]/\\[ASSET\\]\"). All user-owned assets are under the project \"earthengine-legacy\" (e.g., \"projects/earthengine-legacy/assets/users/foo/bar\"). All other assets are under the project \"earthengine-public\" (e.g., \"projects/earthengine-public/assets/LANDSAT\"). Authorization requires the following [IAM](https://cloud.google.com/iam/docs/) permission on the specified resource `name`: - `earthengine.assets.get` |\n\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"fileFormat\": enum (/earth-engine/reference/rest/v1alpha/ImageFileFormat), \"grid\": { object (/earth-engine/reference/rest/v1alpha/PixelGrid) }, \"region\": { object }, \"bandIds\": [ string ], \"visualizationOptions\": { object (/earth-engine/reference/rest/v1alpha/VisualizationOptions) }, \"workloadTag\": string } ``` |\n\n| Fields ||\n|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `fileFormat` | `enum (`[ImageFileFormat](/earth-engine/reference/rest/v1alpha/ImageFileFormat)`)` The output file format in which to return the pixel values. |\n| `grid` | `object (`[PixelGrid](/earth-engine/reference/rest/v1alpha/PixelGrid)`)` Parameters describing the pixel grid in which to fetch data. Defaults to the native pixel grid of the data. |\n| `region` | `object (`[Struct](https://protobuf.dev/reference/protobuf/google.protobuf/#struct)` format)` If present, the region of data to return, specified as a GeoJSON geometry object (see RFC 7946). Since the returned image is always rectangular, the bounding box of the given geometry in the output coordinate system will actually be used. If `grid.dimensions` is also specified then the grid will finally be rescaled to the requested size. |\n| `bandIds[]` | `string` If present, specifies a specific set of bands from which to get pixels. Bands are identified by id, as indicated by the `id` field of an ImageBand proto. |\n| `visualizationOptions` | `object (`[VisualizationOptions](/earth-engine/reference/rest/v1alpha/VisualizationOptions)`)` If present, a set of visualization options to apply to produce an 8-bit RGB visualization of the data, rather than returning the raw data. |\n| `workloadTag` | `string` User supplied tag to track this computation. |\n\n### Response body\n\nIf successful, the response is a generic HTTP response whose format is defined by the method.\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://www.googleapis.com/auth/earthengine`\n- `\n https://www.googleapis.com/auth/earthengine.readonly`\n- `\n https://www.googleapis.com/auth/cloud-platform`\n- `\n https://www.googleapis.com/auth/cloud-platform.read-only`\n\nFor more information, see the [OAuth 2.0 Overview](/identity/protocols/OAuth2)."]]
