GIS 雲端（預覽版）

此連接器允許使用者使用在 GIS Cloud 中產生的任何有效授權金鑰來存取其地圖專案、其中定義的圖層以及這些圖層上包含的圖徵的清單。為了適應功能結構描述的動態性質，連接器將動態查詢服務以取得指定層的功能結構描述。

此連接器適用於以下產品和區域：

服務	Class	Regions
副駕駛工作室	進階	除下列區域外的所有 Power Automate 區域： - 美國政府（GCC） - 美國政府（海灣合作委員會高中） - 由 21Vianet 營運的中國雲 - 美國國防部（DoD）
邏輯應用程式	標準	所有 Logic Apps 區域，但下列區域除外： - Azure Government 區域 - Azure 中國區域 - 美國國防部（DoD）
Power Apps	進階	除下列區域外的所有 Power Apps 區域： - 美國政府（GCC） - 美國政府（海灣合作委員會高中） - 由 21Vianet 營運的中國雲 - 美國國防部（DoD）
Power Automate（自動化服務）	進階	除下列區域外的所有 Power Automate 區域： - 美國政府（GCC） - 美國政府（海灣合作委員會高中） - 由 21Vianet 營運的中國雲 - 美國國防部（DoD）

連絡人
名稱	GIS Cloud 高級支持
URL	https://docs.giscloud.com/rest
Email	premiumsupport@giscloud.com

連接器中繼資料
Publisher	HandyGeo 解決方案
網站	http://www.giscloud.com
隱私策略	https://www.giscloud.com/privacy-policy/
類別	資料;商業智慧

GIS Cloud 是一個 SaaS 平台，提供一流的 Web 和移動地圖渲染以及強大的表單引擎，以滿足您的所有協作製圖需求。 GIS 雲端連接器提供廣泛且強大的 REST API 的子集，可讓自動化驅動地圖專案的大部分常見使用案例。此連接器將允許您列出、更新和訪問 GIS 雲地圖、圖層、用戶，以及創建功能和文件。透過此子集，使用者可以自動執行許多資料驅動的活動，例如建立用於檢查的新功能、建立報告、匯出資料以進行儀表板等...

先決條件

若要使用 GIS 雲端連接器，您必須擁有具有地圖編輯器訂閱的 GIS 雲端使用者帳戶，否則許多動作將無法運作。

如何取得認證

GIS 雲端 REST API 透過 API 金鑰進行保護。如果沒有有效的 API 金鑰，大多數 REST 端點將無法運作。

若要取得有效的 API 金鑰，請導覽至 https://manager.giscloud.com 並使用您的 GIS 雲端帳戶登入。

在右上角，單擊您的用戶名，然後從下拉菜單中選擇“我的帳戶”。

在彈出式視窗中，選取「API 存取」標籤。在「新增 API 金鑰說明」方塊中輸入金鑰的描述性名稱，然後按一下「新增金鑰」。新的模式將顯示您的新 API 金鑰，您必須安全地複製和儲存該金鑰，因為它永遠不會再次顯示。

如需更多參考，請參閱： https://docs.giscloud.com/rest#creating-an-api-key

完成後，您可以建立並測試連接器。

開始使用連接器

第一次設定連接器時，透過 GetCurrentUser 動作進行測試將確認您的 API 金鑰有效，並傳回與 API 金鑰相關聯的帳戶詳細資料。

大多數使用者會在其自動化中使用 GetFeatures、CreateFeature、UpdateFeature 和 DeleteFeature 動作。其他包含的動作將主要用於給定自動化場景的特定情況協調。

典型的自動化案例是將 Gis 雲端功能從 SaaS 資料庫同步到 Dataverse 資料表或 Excel 工作表，以建立 Power BI 儀表板。根據您的資料結構，您可能需要建立自訂 Dataverse 實體。建議自動化 where 利用 GetFeatures 動作上的參數，將限制為過去幾天修改的功能，並僅同步處理這些功能。這將優化自動化的性能。

另一個典型的自動化場景是根據次要資料來源（例如 Dynamics、SalesForce、HTTP 請求甚至 GIS Cloud 本身）自動建立新的 GIS Cloud 功能。為了實現這一目標，建議使用者仔細考慮如何過濾其次要資料來源以觸發特徵建立，並在建立自動化之前完成其 GIS 雲端目標層結構描述，因為這將簡化開發。

最後一個典型的自動化場景是通過將滿足特定條件（即列上設置的特定狀態）的圖徵複製到另一個圖層，然後在成功刪除原始 GIS 雲圖徵時自動“歸檔”GIS 雲圖徵。這可讓作用中的地圖專案保持視覺上乾淨，而不會遺失任何重要資料。

已知問題與限制

PowerApps 的驗證相容性

為了協助與 HandyGeo Services 所發佈的 PCF 地圖元件相容，並避免提示 PowerApps 使用者輸入 API 金鑰，這不易記於使用者，我們已建立連接器，以要求在每個要求中指定 API 金鑰。

功能端點的動態資料結構描述

由於 GIS 雲端中的地理特徵源自使用者上傳的資料，因此結構描述始終是特定於資料集的。因此，來自所有功能端點的承載和回應的結構描述一律是動態的，而且需要支援所使用的 Office 365 產品中的動態結構描述。 PowerAutomate 通常很好地支援這一點，但在 PowerApps 中可能會帶來挑戰。

常見錯誤和補救措施

端點分頁

GIS 雲端端點限制為從單一請求傳回的最多 5,000 筆記錄。雖然REST API支援分頁，但目前無法在聯結器行為中自動包含此內容。

服務保護的 REST API 速率限制

正如任何生產 REST API 服務所預期的那樣，如果在短時間內向 GIS Cloud API 發出過多的請求，則響應將是 5xx 代碼。雖然沒有明確定義特定的速率限制，但 REST API 將支援有限的平行迴圈速率（即大約 20），但高速率可能會導致嚴重故障。失敗的回應可以使用重試原則來管理，但過高的速率會導致問題。

動態功能資料結構描述遺失

由於聯結器需要查詢結構描述定義，如果動態傳遞層ID和/或API金鑰引數，動作將無法快取層結構描述，這需要使用者手動管理傳回的JSON。在參數方塊中輸入動態參數，將其替換為靜態值，結構描述將被適當地快取。

FAQ

GetFeatures 動作傳回太多功能，如何只取得我想要的功能？

建議使用者盡可能利用 where GetFeatures 動作上可用的子句。這可以容納大多數符合 SQL 的 WHERE 子句。對於平台管理的記錄修改日期等欄位，建議使用者在 GetColumns 動作上進行測試，以檢視系統資料行的真實邏輯名稱。

如何將檔案上傳至地圖專案擁有者儲存空間，而不是我自己的儲存空間？

對於動作 UploadFileToPath，如果 API 金鑰不是針對 Map 專案擁有者帳戶，則必須填入參數 Destination Map ID (destination_map) 。這會向 GIS Cloud REST API 發出信號，表明上傳的檔案不是針對已驗證的使用者，而是針對指定地圖專案的擁有者。如果使用者沒有存取地圖的權限，則上傳將不會路由傳送至地圖提供者帳戶。

節流限制

名稱	呼叫	續約期間
每個連線的 API 呼叫	100	60 秒

動作

上傳一個檔案	將檔案上傳至 GIS 雲端儲存空間。
依 ID 取得使用者物件	通過用戶 ID 獲取 GIS 雲用戶對象。
刪除一個圖層	刪除一個 GIS 雲層對象。
刪除一個文件	移除 GIS 雲端儲存中的檔案。
刪除一張地圖	刪除一個 GIS 雲端地圖專案
刪除地圖快取	刪除地圖圖塊快取，以反映透過 API 所做的變更。
刪除特徵	從圖層中刪除指定的 GIS 雲端圖徵物件。
取得一個檔案	從 GIS 雲存儲下載一個文件。
取得圖層上的特徵	獲取圖層對象上的所有 GIS 雲圖物對象。
取得圖層的欄	取得圖層的欄清單
取得所有圖層	獲取所有 GIS 雲層對象。
取得所有地圖	獲取所有 GIS 雲地圖對象。
取得目前的使用者物件	獲取當前的 GIS 雲用戶對象。
在圖層上建立新特徵	獲取圖層對象上的所有 GIS 雲圖物對象。
在地圖上獲取所有圖層	獲取單個 GIS 雲地圖對象的所有圖層對象。
從「功能」欄位取得媒體歸檔	從圖層物件上的 GIS 雲端要素物件欄位取得一個媒體檔案。
更新一個圖層	更新一個 GIS 雲層物件。
更新一張地圖	更新一個 GIS 雲端地圖專案
更新功能	更新圖層物件上的一個 GIS 雲端圖徵物件。
渲染一張地圖	渲染一個 GIS 雲地圖對象的圖像。
獲取一層	獲取所有 GIS 雲層對象。
獲取一張地圖	獲取一個 GIS 雲地圖對象。
獲取功能	在圖層物件上取得一個 GIS 雲端特徵物件。

上傳一個檔案

作業識別碼：: UploadFileToPath

將檔案上傳至 GIS 雲端儲存空間。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
檔案資料	filedata	True	file	要上傳的檔案。
目的地地圖ID	destination_map		integer	共用地圖的地圖 ID。如果設定，則會將檔案上傳至地圖擁有者儲存空間。
檔案路徑	path_to_a_file	True	string	特定檔案的相對路徑

傳回

名稱	路徑	類型	Description
位置	location	string

依 ID 取得使用者物件

作業識別碼：: GetUserDetails

通過用戶 ID 獲取 GIS 雲用戶對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
使用者 ID	user_id	True	integer	用來識別特定使用者的內部使用者 ID
展開屬性	expand		string	透過其中一個 Enum 選項展開回應

傳回

身體: User

刪除一個圖層

作業識別碼：: DeleteLayer

刪除一個 GIS 雲層對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼

刪除一個文件

作業識別碼：: DeleteFileAtPath

移除 GIS 雲端儲存中的檔案。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
檔案名稱	file_name	True	string	SaaS 儲存設備上的特定媒體檔案名稱
檔案路徑	path_to_a_file	True	string	特定檔案的相對路徑

刪除一張地圖

作業識別碼：: DeleteMap

刪除一個 GIS 雲端地圖專案

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
地圖 ID	map_id	True	integer	用來識別特定地圖的內部地圖標識碼

刪除地圖快取

作業識別碼：: DeleteMapCache

刪除地圖圖塊快取，以反映透過 API 所做的變更。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
地圖 ID	map_id	True	integer	用來識別特定地圖的內部地圖標識碼
重新初始化觸發器	init_trigger	True	integer	在執行作業之前，是否應該重新初始化對映
圖層清單	layers		string	要包含的圖層 ID 的 CSV 清單

刪除特徵

作業識別碼：: DeleteFeature

從圖層中刪除指定的 GIS 雲端圖徵物件。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
功能識別碼	feature_id	True	integer	用來識別特定功能的內部功能識別碼
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼

取得一個檔案

作業識別碼：: GetFileByPath

從 GIS 雲存儲下載一個文件。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
檔案路徑	path_to_a_file	True	string	特定檔案的相對路徑
檔案名稱	file_name	True	string	SaaS 儲存設備上的特定媒體檔案名稱

傳回

response: file

取得圖層上的特徵

作業識別碼：: GetFeatures

獲取圖層對象上的所有 GIS 雲圖物對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼
包括幾何圖形	geometry		string	幾何圖形將被封裝的格式。可能的值：'wkt'、'kml' 和 'gml'
EPSG 預測	epsg		integer	輸出投影的 EPSG 代碼。如果未指定，則使用預設地圖投影
空間邊界	bounds		string	用於空間篩選的邊界方塊
SQL 其中	where		string	SQL類型where子句，用於屬性過濾
訂購方式	order_by		string	這必須參考目標 GIS 雲端物件中存在的資料行。依預設，資料行會排序為「以序」排序，但包含 :d esc 會反轉順序。排序方式，格式為“{created\|modified\|created}：[asc\|desc]”，例如 order_by=accessed：desc
項目 Per-Page	perpage		integer	每頁要顯示的結果數（預設值：100，最大值：5000）
頁碼	page		integer	回應的頁碼
無總計	nototal		integer	不計算和顯示結果總數;提高響應時間;用於更快地獲得響應

傳回

此作業會輸出隨機的結果。

取得圖層的欄

作業識別碼：: GetLayerColumns

取得圖層的欄清單

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼

取得所有圖層

作業識別碼：: GetLayers

獲取所有 GIS 雲層對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
展開屬性	expand		string	透過其中一個 Enum 選項展開回應
可見度類型	type		string	依可見度篩選：「公開」、「私人」、「共用」或「私人，共用」
訂購方式	order_by		string	這必須參考目標 GIS 雲端物件中存在的資料行。依預設，資料行會排序為「以序」排序，但包含 :d esc 會反轉順序。排序方式，格式為“{created\|modified\|created}：[asc\|desc]”，例如 order_by=accessed：desc
項目 Per-Page	perpage		integer	每頁要顯示的結果數（預設值：100，最大值：5000）
頁碼	page		integer	回應的頁碼
無總計	nototal	True	integer	不計算和顯示結果總數;提高響應時間;用於更快地獲得響應

傳回

身體: Layers

取得所有地圖

作業識別碼：: GetMaps

獲取所有 GIS 雲地圖對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
可見度類型	type		string	依可見度篩選：「公開」、「私人」、「共用」或「私人，共用」
展開屬性	expand		string	透過其中一個 Enum 選項展開回應
訂購方式	order_by		string	這必須參考目標 GIS 雲端物件中存在的資料行。依預設，資料行會排序為「以序」排序，但包含 :d esc 會反轉順序。排序方式，格式為“{created\|modified\|created}：[asc\|desc]”，例如 order_by=accessed：desc
項目 Per-Page	perpage		integer	每頁要顯示的結果數（預設值：100，最大值：5000）
頁碼	page		integer	回應的頁碼
無總計	nototal		integer	不計算和顯示結果總數;提高響應時間;用於更快地獲得響應

傳回

身體: Maps

取得目前的使用者物件

作業識別碼：: GetCurrentUser

獲取當前的 GIS 雲用戶對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
展開屬性	expand		string	透過其中一個 Enum 選項展開回應

傳回

身體: User

在圖層上建立新特徵

作業識別碼：: CreateFeature

獲取圖層對象上的所有 GIS 雲圖物對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼
承載	payload		dynamic	要從中建立新功能的資料，任何留空的內容都會建立為 null。

傳回

名稱	路徑	類型	Description
位置	location	string

在地圖上獲取所有圖層

作業識別碼：: GetMapLayers

獲取單個 GIS 雲地圖對象的所有圖層對象。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
地圖 ID	map_id	True	integer	用來識別特定地圖的內部地圖標識碼
展開屬性	expand		string	透過其中一個 Enum 選項展開回應
訂購方式	order_by		string	這必須參考目標 GIS 雲端物件中存在的資料行。依預設，資料行會排序為「以序」排序，但包含 :d esc 會反轉順序。排序方式，格式為“{created\|modified\|created}：[asc\|desc]”，例如 order_by=accessed：desc
項目 Per-Page	perpage		integer	每頁要顯示的結果數（預設值：100，最大值：5000）
頁碼	page		integer	回應的頁碼
無總計	nototal		integer	不計算和顯示結果總數;提高響應時間;用於更快地獲得響應

傳回

身體: Layers

從「功能」欄位取得媒體歸檔

作業識別碼：: GetFeatureMediaFile

從圖層物件上的 GIS 雲端要素物件欄位取得一個媒體檔案。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
下載檔案	download		boolean	是否應該直接下載擷取的媒體檔案
檔案路徑	path_to_a_file	True	string	特定檔案的相對路徑
欄位名稱	field_name	True	string	指定圖層上特徵欄位的名稱
功能識別碼	feature_id	True	integer	用來識別特定功能的內部功能識別碼
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼

傳回

response: file

更新一個圖層

作業識別碼：: UpdateLayer

更新一個 GIS 雲層物件。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼
名稱	name		string	圖層名稱

更新一張地圖

作業識別碼：: UpdateMap

更新一個 GIS 雲端地圖專案

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
地圖 ID	map_id	True	integer	用來識別特定地圖的內部地圖標識碼
名稱	name		string	地圖名稱

更新功能

作業識別碼：: UpdateFeature

更新圖層物件上的一個 GIS 雲端圖徵物件。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
功能識別碼	feature_id	True	integer	用來識別特定功能的內部功能識別碼
圖層識別碼	layer_id	True	integer	用來識別特定層的內部層識別碼
承載	payload		dynamic	要更新的新功能資料

渲染一張地圖

作業識別碼：: RenderMap

渲染一個 GIS 雲地圖對象的圖像。

參數

名稱	機碼	必要	類型	Description
API 金鑰	API-Key	True	password	用於授權操作的 GIS 雲 API 密鑰
地圖 ID	map_id	True	integer	用來識別特定地圖的內部地圖標識碼
影像寬度	width		number	影像寬度（以像素為單位）
影像高度	height		number	影像高度（以像素為單位）
使快取失效	invalidate		number	使快取失效
顯示圖層清單	layerlist		number	將圖層列表設置為在圖像中可見
已儲存的影像	justgenerate		number	只需生成圖像即可保存

傳回

response: file

獲取一層

作業識別碼：: GetLayer