Data - Upload Preview
上傳要求可讓呼叫者將數據內容上傳至其 Azure 地圖服務 帳戶。
適用於: S1 定價層。
數據上傳 API 可讓呼叫者將數據內容上傳至 Azure 地圖服務 服務。
您可以在像是以格式上傳 Geofences GeoJSON
集合的案例中使用此 API,以用於我們的 Azure 地圖服務 地理柵欄服務。
注意
Azure 地圖服務 數據服務淘汰
Azure 地圖服務 數據服務 (v1 和 v2) 現在已被取代,將於 9/16/24 淘汰。 若要避免服務中斷,所有對數據服務的呼叫都必須更新,才能使用 9/16/24 Azure 地圖服務 Data Registry 服務。 如需詳細資訊,請參閱 如何建立數據登錄。
提交上傳要求
若要上傳您的內容,您將使用 POST
要求。 要求本文將包含要上傳的數據。 標頭 Content-Type
會設定為數據的內容類型。
例如,若要以 GeoJSON
格式上傳地理柵欄集合,請將要求本文設定為地理柵欄內容。 將 dataFormat
查詢參數設定為 geojson,並將標頭設定 Content-Type
為下列其中一種媒體類型:
application/json
application/vnd.geo+json
application/octet-stream
此處顯示的是要求本文範例,目的是上傳以中心點和半徑顯示為圓形幾何的簡易地理柵欄。 下列範例位於 GeoJSON
:
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-122.126986, 47.639754]
},
"properties": {
"geometryId": "001",
"radius": 500
}
}]
}
數據上傳 API 會執行長時間執行的作業。
數據上傳限制
請注意,目前每個 Azure 地圖服務 帳戶都有數據記憶體限制。
達到記憶體限制之後,所有新的上傳 API 呼叫都會傳 409 Conflict
回 HTTP 錯誤回應。
您一律可以使用 資料刪除 API 來刪除舊/未使用的內容,並建立新上傳的空間。
POST https://{geography}.atlas.microsoft.com/mapData/upload?api-version=1.0&dataFormat={dataFormat}
POST https://{geography}.atlas.microsoft.com/mapData/upload?subscription-key={subscription-key}&api-version=1.0&dataFormat={dataFormat}
URI 參數
名稱 | 位於 | 必要 | 類型 | Description |
---|---|---|---|---|
geography
|
path | True |
string |
此參數會指定 Azure 地圖服務 Creator 資源所在的位置。 有效值為us和 eu。 |
api-version
|
query | True |
string |
Azure 地圖服務 API 的版本號碼。 目前的版本為 1.0 |
data
|
query | True |
正在上傳之內容的數據格式。 |
|
subscription-key
|
query |
string |
Azure 地圖帳戶提供的其中一個 Azure 地圖服務金鑰。 如需如何管理驗證的詳細資訊,請參閱 這篇文章 。 |
要求標頭
名稱 | 必要 | 類型 | Description |
---|---|---|---|
x-ms-client-id |
string |
指定哪個帳戶與 Microsoft Entra ID 安全性模型搭配使用。 它代表 Azure 地圖服務 帳戶的唯一標識符,而且可以從 Azure 地圖服務 管理平面帳戶 API 擷取。 若要在 Azure 地圖服務 中使用 Microsoft Entra ID 安全性,請參閱下列文章以取得指引。 |
要求本文
名稱 | 類型 | Description |
---|---|---|
UploadContent |
object |
要上傳的內容。 |
回應
名稱 | 類型 | Description |
---|---|---|
200 OK |
數據上傳失敗。 上傳的內容不符合所有驗證檢查。 回應本文包含所有遇到的錯誤。 |
|
201 Created |
已成功建立資源。 Headers Location: string |
|
202 Accepted |
僅支援異步要求。 已接受要求:要求已接受進行處理。 請使用位置標頭中的 URL 來重試或存取結果。 Headers Location: string |
|
400 Bad Request |
不正確的要求:一或多個參數未正確指定或互斥。 |
|
401 Unauthorized |
因為訂用帳戶金鑰無效或 Microsoft Entra ID 持有人令牌無效而拒絕存取。 請務必為作用中的 Azure 訂用帳戶和地圖服務資源提供有效的密鑰。 否則,請確認 WWW-Authenticate 標頭中提供 Microsoft Entra ID 持有人令牌的錯誤碼和描述。 Headers WWW-Authenticate: string |
|
403 Forbidden |
許可權、容量或驗證問題。 |
|
404 Not Found |
找不到:找不到要求的資源,但未來可能會再次提供。 |
|
500 Internal Server Error |
處理這個要求時發生錯誤。 請稍後再試一次。 |
安全性
AADToken
這些是 Microsoft Entra OAuth 2.0 流程。 與 Azure 角色型存取控制配對時,可用來控制對 #D23515F49ECB64D7A93E38A4BE1186A24 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務 資源帳戶或子資源的存取權。 任何使用者、群組或服務主體都可以透過內建角色或由一或多個許可權組成的自定義角色來授與存取權,以 Azure 地圖服務 REST API。
若要實作案例,建議您檢視 驗證概念。 總而言之,此安全性定義會透過能夠針對特定 API 和範圍進行訪問控制的物件,提供將應用程式模型化 () 的解決方案。
備註
- 此安全性定義需要使用
x-ms-client-id
標頭來指出應用程式要求存取權 Azure 地圖服務 資源。 這可以從 地圖管理 API 取得。
Authorization URL
專屬於 Azure 公用雲端實例。 主權雲端具有唯一的授權 URL 和 Microsoft Entra ID 設定。
* 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API,從 Azure 管理平面設定 Azure 角色型存取控制。
* Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式設定。
- 如需 Microsoft 身分識別平台 的詳細資訊,請參閱 Microsoft 身分識別平台 概觀。
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
名稱 | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
這是在 Azure 入口網站 或使用PowerShell、CLI、Azure SDK 或 REST API 中建立 Azure 地圖服務 帳戶時所佈建的共用密鑰。
使用此金鑰,任何應用程式都可以存取所有 REST API。 換句話說,此金鑰可作為發行所在帳戶中的主要金鑰。
對於公開的應用程式,我們建議使用機密用戶端應用程式方法來存取 Azure 地圖服務 REST API,以便安全地儲存您的密鑰。
Type:
apiKey
In:
query
SAS Token
這是透過 azure 管理平面透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API,從 Azure 地圖服務 資源上的列出 SAS 作業建立的共用存取簽章令牌。
使用此令牌時,任何應用程式都有權使用 Azure 角色型訪問控制進行存取,並更精細地控制到期、速率和區域 (特定令牌的使用) 。 換句話說,SAS 令牌可用來允許應用程式以比共用密鑰更安全的方式來控制存取。
對於公開的應用程式,我們建議在 地圖帳戶資源 上設定允許的來源特定清單,以限制轉譯濫用,並定期更新 SAS 令牌。
Type:
apiKey
In:
header
範例
Upload GeoJSON data containing geometries that represent a collection of geofences
Sample Request
POST https://us.atlas.microsoft.com/mapData/upload?subscription-key=[subscription-key]&api-version=1.0&dataFormat=geojson
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.126986,
47.639754
]
},
"properties": {
"geometryId": "001",
"radius": 500
}
}
]
}
Sample Response
Location: https://atlas.microsoft.com/mapData/metadata/{udid}?api-version=1.0
Access-Control-Expose-Headers: Location
{
"operationId": "{operationId}",
"status": "Succeeded",
"created": "2020-01-02 1:02:03 AM +00:00",
"resourceLocation": "https://atlas.microsoft.com/mapData/metadata/{resourceId}?api-version=1.0"
}
operation-Location: https://atlas.microsoft.com/mapData/operations/{operationId}?api-version=1.0
Access-Control-Expose-Headers: Location
{
"error": {
"code": "400 Bad Request",
"message": "Upload request failed. Your data has been removed as we encountered the following problems with it: Map data is not a valid GeoJSON geometry."
}
}
{
"error": {
"code": "400 BadRequest",
"message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
}
}
{
"error": {
"code": "401 Unauthorized",
"message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}
}
{
"error": {
"code": "403 Forbidden",
"message": "Permission, capacity, or authentication issues."
}
}
{
"error": {
"code": "404 NotFound",
"message": "Not Found: the requested resource could not be found, but it may be available again in the future."
}
}
{
"error": {
"code": "500 InternalServerError",
"message": "An error occurred while processing the request. Please try again later."
}
}
定義
名稱 | Description |
---|---|
Long |
Long-Running Operations API 的回應模型。 |
OData |
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個物件。 |
OData |
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個回應物件。 |
type |
要求的狀態狀態。 |
Upload |
正在上傳之內容的數據格式。 |
LongRunningOperationResult
Long-Running Operations API 的回應模型。
名稱 | 類型 | Description |
---|---|---|
created |
string |
建立的時間戳。 |
error |
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個物件。 |
|
operationId |
string |
這個長時間執行作業的標識碼。 |
resourceLocation |
string |
位置 URI,以取得所建立資源的詳細數據。 只有在要求成功完成時,才會提供此專案。 |
status |
要求的狀態狀態。 |
|
warning |
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個物件。 |
ODataError
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個物件。
名稱 | 類型 | Description |
---|---|---|
code |
string |
ODataError 程式代碼。 |
details |
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個物件。 |
|
message |
string |
如果有的話,錯誤的人看得懂的描述。 |
target |
string |
如果有的話,造成錯誤的目標。 |
ODataErrorResponse
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個回應物件。
名稱 | 類型 | Description |
---|---|---|
error |
當 Azure 地圖服務 API 中發生錯誤時,會傳回這個物件。 |
type
要求的狀態狀態。
名稱 | 類型 | Description |
---|---|---|
Failed |
string |
要求有一或多個失敗。 |
NotStarted |
string |
要求尚未開始處理。 |
Running |
string |
要求已開始處理。 |
Succeeded |
string |
要求已成功完成。 |
UploadDataFormat
正在上傳之內容的數據格式。
名稱 | 類型 | Description |
---|---|---|
geojson |
string |
GeoJSON 是以 JSON 為基礎的地理空間數據交換格式。 |
zip |
string |
壓縮的數據格式。 |