讀取和寫入空間資料

發行項
04/24/2024

下表列出使用空間 IO 模組讀取和寫入作業所支援的空間檔案格式。

資料格式	讀取	寫入
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KML	✓	✓
KMZ	✓	✓
空間 CSV	✓	✓
已知文字	✓	✓

下列後續各節概述使用空間 IO 模組讀取和寫入空間資料的所有不同工具。

讀取空間資料

atlas.io.read 函數是用來讀取具有空間資料的通用空間資料格式主要函數，例如 KML、GPX、GeoRSS、GeoJSON 和 CSV 檔案。此函數也可以透過 zip 檔案或 KMZ 檔案的形式讀取這些格式的壓縮版本。 KMZ 檔案格式是一種壓縮版本的 KML，也可以包含影像等資產。或者，讀取函數可以採用指向任何這些格式之檔案的 URL。 URL 應該裝載在已啟用 CORS 的端點上，否則應該在讀取選項中提供 Proxy 服務。 Proxy 服務可用來在未啟用 CORS 的網域上載入資源。讀取函數會傳回承諾，將影像圖示新增至地圖，並以非同步方式處理資料，以最小化對 UI 執行緒的影響。

讀取壓縮檔案時，可以是以 zip 或 KMZ 的形式，解壓縮後則會尋找第一個有效檔案。例如，doc.kml 或其他具有有效副檔名的檔案，例如：.kml、.xml、geojson、.json、.csv、.tsv 或 .txt。然後會預先載入 KML 和 GeoRSS 檔案中所參考的影像，以確保其可供存取。無法存取的影像資料可能會載入替代後援影像，或從樣式中移除。從 KMZ 檔案擷取的影像將會轉換成資料 URI。

讀取函數的結果是 SpatialDataSet 物件。此物件會擴充 GeoJSON FeatureCollection 類別。其可以輕鬆地依原狀傳遞至 DataSource，以在地圖上轉譯其特徵。 SpatialDataSet 不僅包含特徵資訊，也可能如下表所述，包含 KML 地面重疊、處理計量和其他詳細資料。

屬性名稱	類型	描述
`bbox`	`BoundingBox`	資料集中所有資料的週框方塊。
`features`	`Feature[]`	資料集內的 GeoJSON 特徵。
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	KML GroundOverlays 的陣列。
`icons`	Record<string, string>	一組圖示 URL。索引鍵 = 圖示名稱，值 = URL。
內容	任意	在空間資料集的文件等級提供的屬性資訊。
`stats`	`SpatialDataSetStats`	空間資料集內容和處理時間的相關統計資料。
`type`	`'FeatureCollection'`	唯讀的 GeoJSON 類型值。

讀取空間資料的範例

載入空間資料範例顯示如何讀取空間資料集，並使用 SimpleDataLayer 類別在地圖上進行轉譯。此程式碼會使用 URL 所指向的 GPX 檔案。如需此範例的原始程式碼，請參閱載入空間資料原始程式碼。

下一個程式碼示範顯示如何將 KML 或 KMZ 讀取和載入至地圖。 KML 可以包含地面重疊，其格式為 ImageLyaer 或 OgcMapLayer。這些重疊必須與特徵分開新增在地圖上。此外，如果資料集有自訂圖示，必須先將這些圖示載入地圖資源，才能載入特徵。

將 KML 載入地圖範例顯示如何將 KML 或 KMZ 檔案載入地圖。如需此範例的原始程式碼，請參閱將 KML 載入對地圖原始程式碼。

您可以選擇性地提供 Proxy 服務，以存取未啟用 CORS 的跨網域資產。讀取函數會先嘗試使用 CORS 存取另一個網域上的檔案。第一次無法使用 CORS 存取另一個網域上的任何資源時，其只會在提供 Proxy 服務時要求更多檔案。讀取函數會將檔案 URL 附加至提供的 Proxy URL 結尾。此程式碼片段顯示如何將 Proxy 服務傳遞至讀取函數：

//Read a file from a URL or pass in a raw data as a string.
atlas.io.read('https://nonCorsDomain.example.com/mySuperCoolData.xml', {
    //Provide a proxy service
    proxyService: window.location.origin + '/YourCorsEnabledProxyService.ashx?url='
}).then(async r => {
    if (r) {
        // Some code goes here . . .
    }
});

下列程式碼片段顯示如何讀取分隔的檔案，並在地圖上轉譯。在此情況下，程式碼會使用具有空間資料行的 CSV 檔案。您必須新增 Azure 地圖服務空間 IO 模組的參考。

<!-- Add reference to the Azure Maps Spatial IO module. -->
<script src="https://atlas.microsoft.com/sdk/javascript/spatial/0/atlas-spatial.min.js"></script>

<script>
    var datasource, delimitedFileUrl = "Chicago_Police_Stations.csv";
    // Download CSV file (delimitedFileUrl) from:
    // https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/main/Static/data/SpatialCSV/Chicago_Police_Stations.csv

    function GetMap() {

        //Instantiate a map object
        var map = new atlas.Map("myMap", {
            center: [-87.628899, 41.874693],
            zoom: 9,
            view: "Auto",
            // Replace <Your Azure Maps Subscription Key> with your Azure Maps subscription key. https://aka.ms/am-primaryKey
            authOptions: {
                authType: 'subscriptionKey',
                subscriptionKey: '{Your-Azure-Maps-Subscription-key}'
            }
        });
    
    //Wait until the map resources are ready.
      map.events.add('ready', function () {
        
        //Create a data source and add it to the map.
        datasource = new atlas.source.DataSource();
        map.sources.add(datasource);
        
        //Add a simple data layer for rendering the data.
        layer = new atlas.layer.SimpleDataLayer(datasource);
        map.layers.add(layer);
        
        //Read a CSV file from a URL or pass in a raw string.
        atlas.io.read(delimitedFileUrl).then(r => {
            if (r) {
                
                //Add the feature data to the data source.
                datasource.add(r);
                
                //If bounding box information is known for data, set the map view to it.
                if (r.bbox) {
                    map.setCamera({
                        bounds: r.bbox,
                        padding: 50
                    });
                }
            }
          });
        });
      }
</script>

寫入空間資料

空間 IO 模組中有兩個主要寫入函數。 atlas.io.write 函數會產生字串，而 atlas.io.writeCompressed 函數會產生壓縮的 zip 檔案。壓縮的 zip 檔案會包含具有空間資料的文字型檔案。這兩個函數都會傳回承諾，以將資料新增至檔案。而且，其都可以寫入下列任何資料：SpatialDataSet、DataSource、ImageLayer、OgcMapLayer、特徵集合、特徵、幾何或這些資料類型之任意組合的陣列。使用任一函數撰寫時，您可以指定想要的檔案格式。如果未指定檔案格式，則會將資料寫入為 KML。

函式搭配空間資料寫入選項範例是一種工具，可示範大部分可與 atlas.io.write 函式搭配使用的寫入選項。如需此範例的原始程式碼，請參閱空間資料寫入選項原始程式碼。

寫入空間資料的範例

拖放空間檔案到地圖上範例可讓您拖放一或多個 KML、KMZ、GeoRSS、GPX、GML、GeoJSON 或 CSV 檔案到地圖上。如需此範例的原始程式碼，請參閱將空間檔案拖放到地圖原始程式碼上。

您可以選擇性地提供 Proxy 服務，以存取未啟用 CORS 的跨網域資產。此程式碼片段顯示您可以併入 Proxy 服務：

atlas.io.read(data, {
    //Provide a proxy service
    proxyService: window.location.origin + '/YourCorsEnabledProxyService.ashx?url='
}).then(
    //Success
    function(r) {
        //some code goes here ...
    }
);

讀取和寫入已知文字 (WKT)

已知文字 (WKT) 是開放地理空間協會 (OGC) 標準，用來將空間幾何表示為文字。許多地理空間系統都支援 WKT，例如使用 PostGIS 外掛程式的 Azure SQL 和 Azure PostgreSQL。如同大部分的 OGC 標準，座標會格式化為「經度緯度」，以符合「x y」慣例。例如，可以使用 WKT 格式將經度 -110 和緯度 45 的點寫入為 POINT(-110 45)。

可以使用 atlas.io.ogc.WKT.read 函數讀取已知文字，並使用 atlas.io.ogc.WKT.write 函數寫入已知文字。

讀取和寫入已知文字 (WKT) 的範例

讀取已知文字範例顯示如何讀取已知的文字字串 POINT(-122.34009 47.60995)，並使用泡泡圖層在地圖上轉譯。如需此範例的原始程式碼，請參閱讀取已知文字原始程式碼。

讀取和寫入已知文字範例顯示如何將已知文字 (WKT) 字串讀取和寫入為 GeoJSON。如需此範例的原始程式碼，請參閱讀取和寫入已知文字原始程式碼。

讀取及寫入 GML

GML 是空間 XML 檔案規格，通常用來作為其他 XML 規格的延伸。可以使用 atlas.io.core.GmlWriter.write 函數，將 GeoJSON 資料以 GML 標籤寫入為 XML。您可以使用 atlas.io.core.GmlReader.read 函數來讀取包含 GML 的 XML。讀取函數有兩個選項：

isAxisOrderLonLat 選項 - 座標的軸順序「緯度、經度」或「經度、緯度」在資料集之間可能有所不同，而且定義不一定完善。根據預設，GML 讀取器會將座標資料讀取為「緯度、經度」，但將此選項設定為 true 會將其讀取為「經度、緯度」。
propertyTypes 選項 - 此選項是索引鍵值查閱資料表，其中索引鍵是資料集中屬性的名稱。值是剖析時，要轉換值的物件類型。支援的類型值如下：string、number、boolean 和 date。如果屬性不在查閱資料表中，或未定義類型，則會將屬性剖析為字串。

當函數偵測到輸入資料為 XML 時，atlas.io.read 函數會預設為 atlas.io.core.GmlReader.read 函數，但資料不是另一個支援空間 XML 格式之一。

GmlReader 會剖析具有下列其中一個 SRID 的座標：

EPSG：4326 (慣用)
EPSG：4269、EPSG：4283、EPSG：4258、EPSG：4308、EPSG：4230、EPSG：4272、EPSG：4271、EPSG：4267、EPSG：4608、EPSG：4674 可能具有少量的錯誤邊界。
EPSG：3857、EPSG：102100、EPSG：3785、EPSG：900913、EPSG：102113、EPSG：41001、EPSG：54004

下一步

請參閱下列文章，以取得更多可新增至地圖的程式碼範例：

新增 OGC 地圖圖層

共用方式為