Samouczek: tworzenie mapy statycznej przy użyciu interfejsów API REST i Python

Fabric Maps są definiowane przez definicję public (map.json), która opisuje mapę podstawową, źródła danych, źródła warstw i zachowanie renderowania.

W tym samouczku pokazano scenariusz ze statycznymi danymi z wykorzystaniem plików przechowywanych w usłudze Lakehouse. W przypadku scenariuszy przesyłania strumieniowego w czasie rzeczywistym przy użyciu usługi Eventstream i Eventhouse zobacz Tworzenie mapy w czasie rzeczywistym przy użyciu interfejsów API REST i Python.

Najbardziej niezawodnym sposobem automatyzacji tworzenia mapy jest zapewnienie wbudowanej definicji mapy, więc mapa jest w pełni skonfigurowana i gotowa do renderowania podczas tworzenia.

Aby uzyskać więcej informacji na temat struktury definicji mapy, zobacz Definicja elementu mapy.

Korzystając z interfejsu API REST usługi Fabric:

  • Tworzenie Lakehouse za pomocą interfejsu REST API Fabric
  • Przekazywanie pliku GeoJSON do usługi OneLake
  • Prześlij niestandardową ikonę znacznika SVG do OneLake
  • Tworzenie definicji map.json odwołującej się do danych usługi Lakehouse
  • Utwórz mapę, korzystając z definicji podanej bezpośrednio

Ten samouczek opiera się na typowym wzorcu automatyzacji w Fabric: utworzyć infrastrukturę → przesłać dane → zdefiniować wizualizację → wyrenderować mapę.

Kiedy używać tego podejścia

Ten wzorzec jest najlepszy dla:

  • Statyczne zestawy danych geoprzestrzennych
  • Warstwy referencyjne (na przykład punkty orientacyjne, granice)
  • Dane historyczne lub przetwarzane wsadowo

W przypadku scenariuszy, które wymagają ciągłego aktualizowania danych (na przykład śledzenia na żywo lub telemetrii), zobacz Tworzenie mapy w czasie rzeczywistym przy użyciu interfejsów API REST i Python.

Wymagania wstępne

  • Python 3.10 lub nowszy
  • Azure CLI
  • Identyfikator obszaru roboczego Fabric
  • Uprawnienia do wywoływania interfejsów API REST Fabric, takich jak:
    • Item.ReadWrite.All

Note

Delegowane zakresy, takie jak Item.ReadWrite.All, są przyznawane zalogowanej tożsamości poprzez przypisaną jej rolę obszaru roboczego. Upewnij się, że tożsamość, której używasz z az login, ma przypisaną rolę Contributor, Member lub Admin na docelowym obszarze roboczym Fabric przed uruchomieniem skryptu.

Authentication

W tym samouczku jest używany program DefaultAzureCredential, który może uwierzytelniać się przy użyciu kilku źródeł poświadczeń lokalnych/deweloperskich. Najprostszym podejściem dla czytelników, którzy są po raz pierwszy, jest logowanie za pomocą Azure CLI (interfejsu wiersza polecenia platformy Azure).

  1. Otwórz terminal.
  2. Run:
az login

DefaultAzureCredential może używać tożsamości zalogowanej do uzyskiwania tokenów dostępu dla:

  • Architektura sieciowa API REST (zasób: https://api.fabric.microsoft.com/.default)
  • Dostęp do usługi OneLake za pośrednictwem interfejsów API i pakietów SDK usługi ADLS Gen2, w tym adresowania opartego na identyfikatorach GUID dla obszarów roboczych i elementów.

Wskazówka

Informacja o https://api.fabric.microsoft.com/.default tej wartości: jest to zakres żądania tokenu, a nie adres URL, który wywołujesz bezpośrednio. Informuje firmę Microsoft Entra, że token dostępu powinien zostać wystawiony dla interfejsu API REST usługi Microsoft Fabric i powinien zawierać wszystkie uprawnienia Fabric, które zostały już przyznane uwierzytelnionej tożsamości (na przykład Item.ReadWrite.All lub Workspace.ReadWrite.All).

Zakres .default jest używany tylko podczas pozyskiwania tokenu i nigdy nie jest wysyłany do punktów końcowych interfejsu API REST Fabric.

Aby uzyskać więcej informacji na temat działania .default zakresu na platformie tożsamości firmy Microsoft, zobacz Zakresy i uprawnienia na platformie tożsamości firmy Microsoft.

Przed uruchomieniem tego samouczka zalecamy zalogowanie się do usługi Microsoft Fabric co najmniej raz:

https://app.fabric.microsoft.com

Logowanie gwarantuje, że tożsamość Fabric, członkostwo w roli obszaru roboczego i przypisania pojemności są w pełni przydzielone przed programowym uzyskaniem tokenu dostępu Microsoft Entra.

Ten krok jest szczególnie przydatny, jeśli:

  • Dopiero zaczynasz korzystać z usługi Microsoft Fabric
  • Obszar roboczy został niedawno utworzony
  • Twoje przypisanie roli zostało ostatnio dodane

Note

Ten samouczek uwierzytelnia za pomocą Entra ID firmy Microsoft poprzez DefaultAzureCredential. Interfejsy API REST sieci szkieletowej nie wymagają sesji przeglądarki, ale logowanie się do interfejsu internetowego sieci szkieletowej może zapobiec problemom z autoryzacją pierwszego uruchomienia powodowanym przez opóźnione przydzielanie ról.

Tworzenie pliku GeoJSON

Plik GeoJSON w tym samouczku jest używany jako warstwa danych mapy. Po utworzeniu pliku zaktualizuj zmienną local_geojson_path , aby odzwierciedlała poprawną ścieżkę.

Skopiuj następujący plik GeoJSON do pustego pliku tekstowego i zapisz go jako starbucks-seattle.geojson:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 999 3rd Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.334389, 47.605278] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 1201 3rd Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.335167, 47.608040] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 221 Pike St" },
      "geometry": { "type": "Point", "coordinates": [-122.340057, 47.609450] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 800 5th Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.330048, 47.604550] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 1420 5th Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.334091, 47.610041] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 1524 7th Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.334915, 47.614498] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 2011 7th Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.338165, 47.616341] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 2001 8th Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.338806, 47.616848] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 4147 University Way NE" },
      "geometry": { "type": "Point", "coordinates": [-122.313873, 47.658298] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 2200 NW Market St" },
      "geometry": { "type": "Point", "coordinates": [-122.384056, 47.668581] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 101 Broadway E" },
      "geometry": { "type": "Point", "coordinates": [-122.320457, 47.620480] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 824 E Pike St" },
      "geometry": { "type": "Point", "coordinates": [-122.320282, 47.614212] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 6501 California Ave SW" },
      "geometry": { "type": "Point", "coordinates": [-122.387016, 47.545376] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 1501 4th Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.336212, 47.610325] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 701 5th Ave" },
      "geometry": { "type": "Point", "coordinates": [-122.330704, 47.604298] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 2344 Eastlake Ave E" },
      "geometry": { "type": "Point", "coordinates": [-122.325874, 47.640884] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 5221 15th Ave NW" },
      "geometry": { "type": "Point", "coordinates": [-122.376595, 47.668210] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 4408 Fauntleroy Way SW" },
      "geometry": { "type": "Point", "coordinates": [-122.377693, 47.564991] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 7303 35th Ave NE" },
      "geometry": { "type": "Point", "coordinates": [-122.290611, 47.682518] }
    },
    {
      "type": "Feature",
      "properties": { "name": "Starbucks - 2742 Alki Ave SW" },
      "geometry": { "type": "Point", "coordinates": [-122.408028, 47.579311] }
    }
  ]
}

Important

Upewnij się, że ścieżka do pliku użyta w local_geojson_path odpowiada miejscu, w którym zapisano plik na komputerze.

Krok 1. Tworzenie nowego pliku projektu języka Python

W tym kroku utworzysz pusty plik języka Python, który utworzysz sekcję po sekcji.

Utwórz nowy plik o nazwie:

create_map_from_geojson.py

Otwórz plik w edytorze.

Krok 2. Instalowanie wymaganych bibliotek i dodawanie wymaganych instrukcji importu

W tym kroku zainstalujesz zależności i dodasz import używany przez skrypt.

Instalowanie wymaganych bibliotek

Run:

pip install httpx azure-identity azure-storage-file-datalake

Do czego służy każda biblioteka

  • httpx: wysyła żądania HTTP do interfejsów API REST sieci szkieletowej.
  • azure-identity: zapewnia DefaultAzureCredential na potrzeby uwierzytelniania Microsoft Entra.
  • azure-storage-file-datalake: przekazuje pliki do usługi OneLake przy użyciu interfejsów API zgodnych z usługą ADLS Gen2.

Dodawanie instrukcji importu do pliku .py

W górnej części create_map_from_geojson.py dodaj:

import base64
import json
import os
import time
import uuid
from pathlib import Path

import httpx
from azure.identity import DefaultAzureCredential
from azure.storage.filedatalake import DataLakeServiceClient

Krok 3. Dodawanie sekcji konfiguracji

W tym kroku zdefiniujesz zmienne używane przez aplikację, w tym identyfikator obszaru roboczego, ścieżki plików i przełączanie funkcji.

Scentralizowanie konfiguracji w jednej Config klasie — zamiast rozpraszania wartości zakodowanych na twardo w funkcjach — daje trzy konkretne korzyści:

  • Przenośność środowiska: identyfikatory obszarów roboczych, ścieżki plików i nazwy zasobów działają w jednym miejscu, dzięki czemu można ponownie uruchomić skrypt względem innego obszaru roboczego lub maszyny, zmieniając kilka wierszy (lub zmiennej środowiskowej) zamiast wyszukiwać kod.
  • Bardziej przejrzyste sygnatury funkcji: funkcje krokowe akceptują pojedynczy obiekt cfg zamiast długich list parametrów, co sprawia, że koordynacja w main() jest łatwa do odczytania.
  • Bezpieczniejsza obsługa danych poufnych: Poufne wartości, takie jak identyfikator obszaru roboczego, są wczytywane ze zmiennych środowiskowych, dzięki czemu nigdy nie są zapisywane w repozytorium razem ze skryptem.

Dodaj poniższe elementy pod instrukcjami import:

# =========================================================
# Configuration (centralized)
# =========================================================

class Config:
    """
    Central configuration: workspace ID, file paths, resource names, and
    toggles for the optional custom SVG marker. A single instance is built
    in main() and passed to each step function.
    """
    def __init__(self):
        # Workspace
        self.workspace_id = os.environ.get("FABRIC_WORKSPACE_ID", "")
        if not self.workspace_id:
            raise RuntimeError("Set FABRIC_WORKSPACE_ID environment variable before running the script.")

        # Local file (source) and OneLake destination paths (inside Lakehouse Files/)
        self.local_geojson_path = Path(r"C:\tutorial\starbucks-seattle.geojson")
        self.geojson_relative_path = "Files/vector/starbucks-seattle.geojson"

        # Optional SVG marker settings
        self.svg_relative_path = "Files/icons/starbucks-marker.svg"
        self.use_custom_svg_marker = True
        self.builtin_icon_name_fallback = "BuildingShop"

        # SVG content (kept < 1 MB, scales cleanly)
        self.starbucks_marker_svg = """\
<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
  <path d="M32 2C20.4 2 11 11.4 11 23c0 15.6 18.7 36.6 19.5 37.5a2 2 0 0 0 3 0C34.3 59.6 53 38.6 53 23 53 11.4 43.6 2 32 2z"
        fill="#006241" stroke="#ffffff" stroke-width="2"/>
  <circle cx="32" cy="23" r="13" fill="#ffffff" opacity="0.95"/>
  <path d="M26 20h12v10c0 3-2.5 5-6 5s-6-2-6-5V20z" fill="#006241"/>
</svg>
"""

        # Resource display names / descriptions
        self.lakehouse_display_name = "lh_starbucks_seattle"
        self.lakehouse_description = "Stores Starbucks Seattle GeoJSON + marker icon for a Fabric Maps tutorial"

        self.map_display_name = "My Fabric Map"
        self.map_description = "Created using Fabric Maps REST API"

Ustawianie identyfikatora obszaru roboczego przy użyciu zmiennej środowiskowej

Zamiast trwale zapisywać identyfikator obszaru roboczego bezpośrednio w skrypsie, ten samouczek odczytuje go ze zmiennej środowiskowej. Pozwala to zachować wartości specyficzne dla środowiska poza kodem źródłowym i umożliwia ponowne użycie skryptu między obszarami roboczymi lub maszynami bez jego edytowania.

Przed uruchomieniem skryptu utwórz zmienną środowiskową o nazwie FABRIC_WORKSPACE_ID.

Important

Zmienna środowiskowa ustawiona z terminalu istnieje tylko wewnątrz tej jednej sesji terminalu. Nie jest współdzielony z innymi oknami terminala, z oknami używającymi innego typu powłoki ani z procesami uruchamianymi poza tym terminalem — w tym ze skryptami uruchamianymi za pomocą przycisku Uruchom w VS Code, który często uruchamia własny terminal. Jeśli skrypt nie może odnaleźć zmiennej, kończy się niepowodzeniem z parametrem Set FABRIC_WORKSPACE_ID environment variable before running the script.

Aby tego uniknąć, uruchom skrypt z sesji terminalu same gdzie ustawisz zmienną lub ustawisz ją trwale (zobacz sekcje Windows i macOS/Linux), aby każda nowa sesja terminalu pobierała ją automatycznie.

Ustawianie zmiennej środowiskowej na Windows

W systemie Windows zmienną można ustawić w dowolnym terminalu obsługującym zmienne środowiskowe — PowerShell, Windows PowerShell, oknach programu PowerShell lub Wiersza polecenia wbudowanych w programy Visual Studio i Visual Studio Code, Terminal Windows oraz w większości innych powłok.

Uruchom następujące polecenie w programie PowerShell lub zintegrowanym terminalu programu VS Code:

$env:FABRIC_WORKSPACE_ID="<WORKSPACE_ID>"

Aby potwierdzić, że zmienna jest ustawiona:

echo $env:FABRIC_WORKSPACE_ID

Spowoduje to ustawienie zmiennej tylko dla bieżącej sesji terminalu.

Ustawianie trwałej zmiennej środowiskowej (Windows)

Aby udostępnić zmienną w przyszłych sesjach, użyj jednej z następujących opcji:

  • PowerShell (jednolinijkowe polecenie): Uruchom setx FABRIC_WORKSPACE_ID "<WORKSPACE_ID>". Polecenie setx zapisuje dane w środowisku użytkownika, ale nie aktualizuje bieżącego terminalu — zamknij i otwórz ponownie terminal (lub otwórz nowy) przed uruchomieniem skryptu.
  • Graficzny interfejs użytkownika:
    1. Otwórz okno Właściwości systemu.
    2. Wybierz pozycję Zaawansowane ustawienia systemowe.
    3. Wybierz pozycję Zmienne środowiskowe.
    4. W sekcji Zmienne użytkownika wybierz pozycję Nowy.
    5. Wejść:
      • Nazwa: FABRIC_WORKSPACE_ID
      • Wartość: identyfikator obszaru roboczego
    6. Wybierz OK, aby zapisać.
    7. Zamknij i otwórz ponownie terminal przed ponownym uruchomieniem skryptu.

Ustawianie zmiennej środowiskowej w systemie macOS lub Linux

W systemach macOS i Linux można ustawić zmienną w dowolnej powłoce obsługującej export — Bash, Zsh (domyślna we współczesnych wersjach macOS), Fish (z nieco inną składnią), a także w zintegrowanych terminalach w Visual Studio Code i innych edytorach.

Run:

export FABRIC_WORKSPACE_ID="<WORKSPACE_ID>"

Aby potwierdzić, że zmienna jest ustawiona:

echo $FABRIC_WORKSPACE_ID

To ustawia zmienną tylko dla bieżącej sesji powłoki.

Ustawianie trwałej zmiennej środowiskowej (macOS lub Linux)

Aby udostępnić tę zmienną w przyszłych sesjach, dodaj wiersz export do profilu powłoki:

  • Zsh (ustawienie domyślne w systemie macOS): ~/.zshrc
  • Bash: ~/.bashrc (Linux) lub ~/.bash_profile (macOS)
  • Fish: uruchom set -Ux FABRIC_WORKSPACE_ID "<WORKSPACE_ID>" zamiast edytować plik

Po zaktualizowaniu profilu otwórz nowy terminal lub uruchom source ~/.zshrc (lub odpowiedni plik), aby zmiana obowiązywała.

Note

Wartości geojson_relative_path i svg_relative_path definiują lokalizację w obszarze Lakehouse Files. Te ścieżki są względne względem katalogu głównego Lakehouse i służą zarówno do przesyłania plików, jak i odwoływania się do nich w definicji mapy.

Krok 4. Dodawanie funkcji pomocnika

W tym kroku wydzielasz zagadnienia przekrojowe — uwierzytelnianie, tworzenie nagłówków, monitorowanie operacji długotrwałych oraz ponawialne przesyłanie danych w płaszczyźnie danych — do niewielkiego zestawu pomocniczych funkcji wielokrotnego użytku, z których może korzystać każda funkcja kroku.

Scentralizowanie tych kwestii w funkcjach pomocniczych — zamiast umieszczania ich bezpośrednio w każdym miejscu wywołania — daje trzy konkretne korzyści:

  • Jedno źródło prawdy dla zagadnień przekrojowych: uwierzytelnianie, nagłówki i odpytywanie LRO są wymagane przy niemal każdym wywołaniu interfejsu API. Scentralizowanie ich sprawia, że każda funkcja krokowa koncentruje się na własnym zasobie, zamiast ponownie implementować logikę pozyskiwania tokenów i ponawiania prób.
  • Odporność bez bałaganu: Funkcje pomocnicze przejmują obsługę stanów przejściowych — asynchronicznego aprowizowania, opóźnień propagacji w backendzie i błędów przesyłania podlegających ponowieniu — dzięki czemu funkcje krokowe pozostają krótkie i czyta się je jak listę kontrolną.
  • Łatwiejsze do uczenia i modyfikowania: każdy pomocnik jest wprowadzany raz i ponownie używany. Jeśli Fabric zmieni wzorzec LRO lub zakres uwierzytelniania, poprawiasz to w jednym miejscu.

Pomocnicy dodani w tym kroku to:

  • Narzędzia pomocnicze uwierzytelniania: tworzenie nagłówków dla interfejsów API REST platformy Fabric (oraz punktów końcowych LRO klastra Power BI)
  • FabricClient: lekkie opakowanie do spójnych wywołań interfejsu API
  • moduł obsługi LRO handler: odpytywanie długotrwałych operacji przy użyciu Location / x-ms-operation-id / Retry-After, w tym odpowiedzi typu 200-with-Running, punktów końcowych klastra Power BI oraz ładunków zakończenia zawierających wyłącznie stan (rozstrzygane przez displayName)
  • Pomocnik ładunku definicji: kodowanie map.json base64 dla definicji wbudowanych
  • Pomocniki przesyłania do OneLake: przesyłanie plików GeoJSON i SVG do Lakehouse Files z ponawianiem prób

Note

Ten samouczek obejmuje dwie płaszczyzny:

  • Warstwa sterowania (interfejsy API REST usługi Fabric): tworzenie elementów Lakehouse i Map
  • Płaszczyzna danych (OneLake DFS): przekazywanie plików do usługi Lakehouse

Obie są wymagane do pełnego skonfigurowania mapy.

Tworzenie funkcji pomocnika uwierzytelniania

Każde wywołanie interfejsu API REST usługi Fabric wykonywane w tym samouczku zawiera token dostępu Microsoft Entra (token okaziciela) w nagłówku Authorization. Zamiast pozyskiwać tokeny doraźnie, ten krok opakowuje DefaultAzureCredential w mały TokenProvider i udostępnia konstruktor nagłówków specyficzny dla odbiorców dla każdej rodziny punktów końcowych wywoływanej przez skrypt.

Scentralizowanie pozyskiwania tokenów i konstruowania nagłówków w pomocnikach — zamiast uzyskiwania tokenów w każdej lokacji połączeń — zapewnia trzy konkretne korzyści:

  • Scentralizowane poświadczenie: Pojedynczy DefaultAzureCredential jest opakowywany w TokenProvider i wykorzystywany ponownie przy każdym wywołaniu interfejsu API, więc wykrywanie tożsamości (Azure CLI, VS Code, tożsamość zarządzana itp.) następuje tylko raz.
  • Tokeny uwzględniające odbiorców: interfejsy API REST usługi Fabric i punkty końcowe LRO klastra usługi Power BI wymagają tokenów wystawionych dla różnych odbiorców. Oddzielny konstruktor nagłówków dla każdej grupy odbiorców zachowuje właściwy kontekst bezpośrednio obok miejsca wywołania, dzięki czemu od razu widać, do którego punktu końcowego jest kierowana dana funkcja.
  • Tworzony od nowa przy każdym żądaniu: konstruktory nagłówków tworzą nagłówek Authorization na bieżąco, zamiast samodzielnie przechowywać token w pamięci podręcznej. Bazowe poświadczenie jest odnawiane transparentnie, więc miejsca wywołania nigdy nie muszą martwić się o jego wygaśnięcie.

W tym samouczku wywoływane są interfejsy API REST usługi Fabric przy użyciu delegowanych zakresów uprawnień, takich jak Item.ReadWrite.All (lub Lakehouse.ReadWrite.All w przypadku operacji specyficznych dla Lakehouse).

Dodaj następujące elementy po Config klasie:

# =========================================================
# Auth helpers
#
# Authentication utilities built on `DefaultAzureCredential` that acquire and
# construct Authorization headers for calling Fabric REST APIs.
# =========================================================

class TokenProvider:
    """
    Thin wrapper around `DefaultAzureCredential` that acquires Entra access
    tokens. `_fabric_headers()` and `_pbi_headers()` call `get()` per
    request so the Authorization header is always fresh; the underlying
    credential refreshes transparently.
    """
    def __init__(self):
        self._cred = DefaultAzureCredential()

    def get(self, scope: str) -> str:
        return self._cred.get_token(scope).token


_tokens = TokenProvider()


def _fabric_headers() -> dict[str, str]:
    """
    Build headers for Fabric REST API calls.

    This function is called each time we make a Fabric REST call so the token is fresh.
    """
    return {
        "Authorization": f"Bearer {_tokens.get('https://api.fabric.microsoft.com/.default')}",
        "Content-Type": "application/json"
    }


def _pbi_headers() -> dict[str, str]:
    """
    Build headers for polling Power BI cluster LRO endpoints
    (e.g., df-*.analysis.windows.net) that require a Power BI audience token.
    """
    return {
        "Authorization": f"Bearer {_tokens.get('https://analysis.windows.net/powerbi/api/.default')}",
        "Content-Type": "application/json"
    }

Note

Niektóre operacje długotrwałe usługi Fabric (LRO) są obsługiwane w punktach końcowych klastrów Power BI (*.analysis.windows.net), a nie w api.fabric.microsoft.com. Te punkty końcowe wymagają tokenu odbiorcy usługi Power BI, więc moduł pomocniczy LRO automatycznie przełącza się na _pbi_headers(), gdy wykryje ten adres URL do odpytywania.

Utwórz otoczkę klienta Fabric

Większość wywołań interfejsu API REST usługi Fabric w tym samouczku wysyła te same nagłówki Authorization i Content-Type. Zamiast powtarzać je w każdym miejscu wywołania, ten samouczek opakowuje httpx.Client w niewielką funkcję FabricClient, która automatycznie dołącza nagłówki, a jednocześnie nadal zwraca surowe httpx.Response, aby każde miejsce wywołania mogło sprawdzić kody stanu (na przykład, aby odróżnić 201 od 202).

Opakowanie httpx.Client w ten sposób — zamiast przekazywać headers=_fabric_headers() w każdym miejscu wywołania — daje dwie konkretne korzyści:

  • Nagłówki w jednym miejscu: każde miejsce wywołania automatycznie pobiera najnowsze _fabric_headers(), dzięki czemu nowe żądanie nie może zostać przypadkowo wysłane bez nagłówka Authorization.
  • Kody stanu pozostają widoczne: request() zwraca surowe httpx.Response zamiast zdekodowanego formatu JSON, dzięki czemu miejsca wywołania mogą nadal rozgałęziać logikę na podstawie kodu stanu (201 vs 202) i analizować nagłówki, takie jak Location lub Retry-After, na potrzeby obsługi LRO.

Dodaj następujące elementy po funkcjach pomocnika uwierzytelniania:

# =========================================================
# FabricClient (minimal wrapper so call sites stay clean)
# =========================================================

class FabricClient:
    """
    Small wrapper around httpx.Client so we don't repeat headers everywhere.

    Keeps the tutorial behavior:
    - request() returns the raw httpx.Response so the caller can handle 201 vs 202.
    """
    def __init__(self, http_client: httpx.Client):
        self._http = http_client

    def request(self, method: str, url: str, *, json_body=None) -> httpx.Response:
        return self._http.request(method, url, headers=_fabric_headers(), json=json_body)

Utwórz funkcję pomocniczą LRO

Kilka interfejsów API REST platformy Fabric używanych w tym samouczku — takich jak Create Lakehouse i Create Map — obsługuje operacje długotrwałe (LRO).

Te interfejsy API mogą zwracać odpowiedzi w kilku wzorcach:

  • 201 Created z treścią zasobu osadzoną bezpośrednio (synchronicznie)
  • 202 Accepted z nagłówkiem Location wskazującym adres URL stanu operacji (asynchronicznie)
  • 202 Accepted z nagłówkiem x-ms-operation-id zamiast Location (asynchroniczna forma alternatywna)
  • 200 OK z status: "Running" lub status: "NotStarted" podczas sondowania (nadal w toku)
  • 200 OK z status: "Succeeded", ale bez identyfikatora zasobu w treści (zakończono pomyślnie; rozwiąż problem, wyświetlając listę i dopasowując displayName)

Aby zapewnić spójne obsługę wszystkich tych elementów, należy utworzyć jedną funkcję pomocnika, która:

  1. Zwraca identyfikator zasobu natychmiast, jeśli początkowa odpowiedź już go zawiera.
  2. W przeciwnym razie odpytuje adres URL operacji (utworzony na podstawie Location lub x-ms-operation-id) za pomocą Retry-After.
  3. 200 OK status: "Running" / "NotStarted"Traktuje jako nadal w toku i kontynuuje sondowanie.
  4. W przypadku powodzenia zwraca identyfikator zasobu z treści odpowiedzi, a jeśli nie jest to możliwe, przechodzi do wylistowania zasobów i dopasowuje je na podstawie displayName (z ponownymi próbami), gdy treść odpowiedzi zawiera wyłącznie status.
  5. Używa _pbi_headers(), gdy adres URL sondowania znajduje się w klastrze Power BI (*.analysis.windows.net), a w przeciwnym razie używa nagłówków Fabric.

Ta pojedyncza funkcja pomocnicza eliminuje potrzebę stosowania funkcji pomocniczych „wyszukiwania po nazwie” dla każdego zasobu — każda funkcja create_* w tym samouczku wywołuje _handle_lro z odpowiednimi list_url i match_display_name.

Dodaj następujące elementy po FabricClient klasie:

# =========================================================
# LRO handler 
# =========================================================

def _handle_lro(
    client: httpx.Client,
    initial_response: httpx.Response,
    *,
    list_url: str | None = None,
    match_display_name: str | None = None,
    id_field: str = "id",
    max_attempts: int = 10,
    delay: int = 5,
) -> str:
    """
    Handle a Fabric long-running operation (LRO) and return the resource id.

    Supports the response patterns used by Fabric REST APIs:
    - 200/201 with the resource body inline (synchronous).
    - 202 with a `Location` header or `x-ms-operation-id` (asynchronous).
    - 200 with `status: "Running"` / `"NotStarted"` while polling.
    - 200 with `status: "Succeeded"` but no id (resolve by listing and matching `displayName`).

    Polling uses `Retry-After` and switches to a Power BI audience token when
    the operation URL is on `*.analysis.windows.net`.
    """
    # Sync 200/201 with body: return the id immediately.
    if initial_response.status_code in (200, 201):
        try:
            body = initial_response.json() if initial_response.content else {}
        except ValueError:
            body = {}
        if isinstance(body, dict) and body.get(id_field):
            return body[id_field]

    # Location header, with x-ms-operation-id fallback.
    op_url = initial_response.headers.get("Location")
    if not op_url:
        op_id = initial_response.headers.get("x-ms-operation-id")
        if op_id:
            op_url = f"https://api.fabric.microsoft.com/v1/operations/{op_id}"
        else:
            raise RuntimeError(
                f"Missing LRO Location/x-ms-operation-id. "
                f"status={initial_response.status_code} body={initial_response.text[:500]!r}"
            )

    # Audience-aware polling: Power BI cluster endpoints need a different token.
    poll_headers = _pbi_headers() if "analysis.windows.net" in op_url else _fabric_headers()
    retry_after = int(initial_response.headers.get("Retry-After", "5"))

    while True:
        time.sleep(retry_after)
        poll = client.get(op_url, headers=poll_headers)

        if poll.status_code == 202:
            retry_after = int(poll.headers.get("Retry-After", "5"))
            continue

        poll.raise_for_status()
        body = poll.json() if poll.content else {}
        status = body.get("status") if isinstance(body, dict) else None

        if status in ("Running", "NotStarted"):
            retry_after = int(poll.headers.get("Retry-After", "5"))
            continue
        if status == "Failed":
            raise RuntimeError(f"LRO failed. Body: {body}")

        if isinstance(body, dict) and body.get(id_field):
            return body[id_field]

        # Status-only success: list and match by displayName, with retries.
        if status == "Succeeded" and list_url and match_display_name:
            for attempt in range(max_attempts):
                r = client.get(list_url, headers=_fabric_headers())
                r.raise_for_status()
                match = next(
                    (i for i in r.json().get("value", []) if i.get("displayName") == match_display_name),
                    None,
                )
                if match and match.get(id_field):
                    return match[id_field]
                time.sleep(delay)
            raise RuntimeError(
                f"LRO succeeded but resource not visible after retries. "
                f"match_display_name={match_display_name!r}"
            )

        raise RuntimeError(f"LRO completed but no resource id was returned. Body: {body}")

Note

Nowo utworzone zasoby mogą nie być widoczne natychmiast przy wywoływaniu interfejsów API służących do wyświetlania listy z powodu opóźnień propagacji w systemach zaplecza. Funkcja pomocnika automatycznie ponawia próbę, dopóki zasób nie stanie się widoczny.

Pomocnik ładunku definicji

Podczas tworzenia mapy z definicją publiczną interfejs API REST tworzenia mapy oczekuje, że każda część w definition.parts będzie zawierać ładunek zakodowany w formacie base64 przy użyciu "payloadType": "InlineBase64". Funkcja pomocnicza _json_to_b64 koduje obiekt Python dict (twój map.json) do tego formatu, aby create_map mógł umieścić go bezpośrednio w treści żądania.

Dodaj następujące elementy po _handle_lro funkcji:

# =========================================================
# Definition payload helper
#
# Encodes map.json as base64 for inline Create map payloads.
# =========================================================

def _json_to_b64(obj: dict) -> str:
    """
    Convert a Python dict to base64-encoded JSON text.

    Fabric Map "Create map with definition inline" requires:
    - definition.parts[].payloadType = InlineBase64
    - definition.parts[].payload     = base64(json(map_json))
    """
    return base64.b64encode(json.dumps(obj).encode("utf-8")).decode("utf-8")

Pomocniki ładowania OneLake

Usługa OneLake wspiera interfejsy API dla usług ADLS i Blob, umożliwiając adresowanie oparte na unikalnym identyfikatorze globalnym (GUID) dla obszarów roboczych i elementów.

https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/<path>/<fileName>

Dodaj:

# ===============================================================================================
# ONE LAKE UPLOAD HELPERS
# OneLake supports GUID-based addressing:
#   https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/<path>/<fileName> 
# We use the ADLS Gen2 SDK (DataLakeServiceClient) to upload files into the Lakehouse Files area.
# ===============================================================================================

def _onelake_client() -> DataLakeServiceClient:
    """
    Build a DataLakeServiceClient against the OneLake DFS endpoint,
    authenticated with `DefaultAzureCredential`. Used by `_upload_with_retry`
    to write files into the Lakehouse Files area.
    """
    return DataLakeServiceClient(
        account_url="https://onelake.dfs.fabric.microsoft.com",
        credential=DefaultAzureCredential()
    )


def _upload_with_retry(
    workspace_guid: str,
    item_guid: str,
    dest_relative_path: str,
    content: bytes,
    attempts: int = 6
) -> None:
    """
    Upload bytes into OneLake at `<workspace GUID>/<item GUID>/<relative path>`.
    Retries with linear backoff because a newly created Lakehouse can
    briefly return errors before its `Files/` area is provisioned.
    """
    service = _onelake_client()
    fs = service.get_file_system_client(file_system=workspace_guid)

    dest_path = f"{item_guid}/{dest_relative_path}".replace("\\", "/")

    last_exc = None
    for i in range(attempts):
        try:
            fs.get_file_client(dest_path).upload_data(content, overwrite=True)
            return
        except Exception as exc:
            last_exc = exc
            time.sleep(2 + i)

    raise RuntimeError(f"Upload failed after {attempts} attempts: {last_exc}")

Wskazówka

Możesz sprawdzić, czy plik został pomyślnie przesłany, przechodząc do obszaru Lakehouse Files w portalu Fabric.

Tworzenie podstawowych funkcji

Następnie dodasz podstawowe funkcje, które definiują przepływ pracy. Wszystkie są wywoływane z main().

  1. Stwórz Lakehouse
  2. Przekazywanie pliku GeoJSON do usługi Lakehouse
  3. Prześlij niestandardowy znacznik SVG (opcjonalnie)
  4. Tworzenie definicji mapy (map.json)
  5. Tworzenie mapy z wbudowaną definicją

Stwórz Lakehouse

create_lakehouse Tworzy usługę Lakehouse, która przechowuje plik GeoJSON i opcjonalny znacznik SVG używany przez mapę.

Ta funkcja:

  • Wysyła żądanie POST do punktu końcowego REST usługi Lakehouse z użyciem displayName i description z Twojej konfiguracji
  • Przekazuje odpowiedź do _handle_lro, gdzie jest ona obsługiwana w jednolity sposób dla odpowiedzi synchronicznych (201), asynchronicznych (202/LRO) i zawierających wyłącznie stan
  • Zwraca identyfikator usługi Lakehouse do użycia w kolejnych krokach

Dodaj następujące elementy po _upload_with_retry funkcji:

# =========================================================
# Step 1: Create a Lakehouse
# =========================================================

def create_lakehouse(client: httpx.Client, fabric: FabricClient, cfg: Config) -> str:
    """
    Create a Lakehouse and return its item ID.
    """
    lakehouse_url = f"https://api.fabric.microsoft.com/v1/workspaces/{cfg.workspace_id}/lakehouses"
    lakehouse_payload = {
        "displayName": cfg.lakehouse_display_name,
        "description": cfg.lakehouse_description
    }

    lh_resp = fabric.request("POST", lakehouse_url, json_body=lakehouse_payload)

    lakehouse_id = _handle_lro(
        client,
        lh_resp,
        list_url=lakehouse_url,
        match_display_name=cfg.lakehouse_display_name,
    )

    print("Lakehouse created. Lakehouse ID:", lakehouse_id)
    return lakehouse_id

Przekazywanie pliku GeoJSON do usługi Lakehouse

upload_geojson przekazuje lokalny plik GeoJSON do obszaru Lakehouse Files , gdzie staje się źródłem danych przestrzennych, które mapa odczytuje w czasie renderowania.

Jest to pierwszy krok, który przechodzi z płaszczyzny sterowania Fabric (REST) do płaszczyzny danych OneLake (ADLS Gen2). Funkcja odczytuje plik lokalny do pamięci i deleguje operację do _upload_with_retry, który wykonuje dzielone na fragmenty przesyłanie do DFS i ponawia próby w przypadku przejściowych błędów.

Dodaj następujące elementy po create_lakehouse funkcji:

# =========================================================
# Step 2: Upload GeoJSON to the Lakehouse
# =========================================================

def upload_geojson(cfg: Config, lakehouse_id: str) -> None:
    """
    Upload the local GeoJSON file to the Lakehouse Files area at
    `cfg.geojson_relative_path` using the OneLake DFS endpoint.
    """
    _upload_with_retry(
        workspace_guid=cfg.workspace_id,
        item_guid=lakehouse_id,
        dest_relative_path=cfg.geojson_relative_path,
        content=cfg.local_geojson_path.read_bytes()
    )
    print("Uploaded GeoJSON to:", cfg.geojson_relative_path)

Prześlij niestandardowy znacznik SVG

upload_svg_marker przekazuje niestandardową ikonę SVG do tej samej usługi Lakehouse, aby mapa mogła renderować każdą funkcję z tym znacznikiem zamiast wbudowanego. Krok jest opcjonalny i ogrodzony przez cfg.use_custom_svg_marker — gdy flaga to False, funkcja zwraca natychmiast, a mapa wraca do wbudowanego znacznika.

Podobnie jak upload_geojson, ta funkcja powierza faktyczne przesyłanie elementowi _upload_with_retry.

Dodaj następujące elementy po upload_geojson funkcji:

# =========================================================
# Step 3: Upload a custom SVG marker (optional)
# =========================================================

def upload_svg_marker(cfg: Config, lakehouse_id: str) -> None:
    """
    Upload a custom SVG marker to the Lakehouse at
    `cfg.svg_relative_path` when `cfg.use_custom_svg_marker` is True;
    otherwise return without uploading.
    """
    if not cfg.use_custom_svg_marker:
        return

    _upload_with_retry(
        workspace_guid=cfg.workspace_id,
        item_guid=lakehouse_id,
        dest_relative_path=cfg.svg_relative_path,
        content=cfg.starbucks_marker_svg.encode("utf-8")
    )
    print("Uploaded custom SVG marker to:", cfg.svg_relative_path)

Wskazówka

Znaczniki SVG zachowują dobrą jakość przy różnych poziomach powiększenia i gęstościach pikseli ekranu, dzięki czemu dobrze nadają się na ikony map.

Kompilowanie map.json

build_map_json kompiluje i zwraca ładunek map.json definiujący zawartość mapy Fabric. Ładunek jest zgodny ze schematem definicji elementu mapy i składa się z czterech sekcji: dataSources (gdzie pochodzą dane), iconSources (opcjonalne znaczniki niestandardowe), layerSources (co jest odczytywane i jak często) oraz layerSettings (jak wynik jest renderowany na mapie).

W tym samouczku element dataSources wskazuje na utworzony wcześniej zasób Lakehouse (itemType: "Lakehouse"), a pojedynczy wpis w layerSources to warstwa pliku GeoJSON (type: "geojson"), która odczytuje plik przesłany za pomocą relativePath. refreshIntervalMs jest ustawione na wartość 0, ponieważ plik źródłowy jest statyczny — mapa renderuje plik raz i nie sprawdza zmian.

Odpowiadający layerSettings wpis renderuje każdy obiekt jako obiekt marker i pokazuje właściwość name GeoJSON we wskazówkach. Gdy cfg.use_custom_svg_marker ma wartość True, dodawany jest wpis iconSources, który odwołuje się do przesłanego pliku SVG, a właściwość iconOptions.image warstwy używa klucza złożonego <layerSettingId>:<iconId>, aby powiązać znacznik z tą ikoną. Gdy jest False, warstwa spada z powrotem do wbudowanego znacznika (cfg.builtin_icon_name_fallback) stylizowany z starbucks-zielony wypełnienie.

Aby uzyskać więcej informacji na temat interfejsu API REST definicji mapy, zobacz Definicja elementu mapy. Przykład elementu map.json można znaleźć w przykładzie MapDetails.

Dodaj następujące elementy po upload_svg_marker funkcji:

# =========================================================
# Step 4: Build map.json
# =========================================================

def build_map_json(cfg: Config, lakehouse_id: str) -> dict:
    """
    Build and return the map.json payload for the Fabric Map.

    Wires `dataSources` to the Lakehouse created earlier, defines a
    single GeoJSON layer in `layerSources` that reads the uploaded file
    via `cfg.geojson_relative_path` with `refreshIntervalMs: 0` (the
    source is static), and configures `layerSettings` to render each
    feature as a marker. When `cfg.use_custom_svg_marker` is True, adds
    an `iconSources` entry for the uploaded SVG and binds the layer to
    it via a `<layerSettingId>:<iconId>` composite key; otherwise falls
    back to a built-in marker.
    """
    layer_source_id = str(uuid.uuid4())
    layer_setting_id = str(uuid.uuid4())
    icon_source_id = str(uuid.uuid4())

    custom_svg_marker = f"{layer_setting_id}:{icon_source_id}"
    icon_source_name = "Starbucks Marker"

    map_json = {
        "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/map/definition/2.0.0/schema.json",
        "basemap": {},

        "dataSources": [
            {"itemType": "Lakehouse", "workspaceId": cfg.workspace_id, "itemId": lakehouse_id}
        ],

        "iconSources": (
            [
                {
                    "id": icon_source_id,
                    "name": icon_source_name,
                    "type": "svg",
                    "itemId": lakehouse_id,
                    "relativePath": cfg.svg_relative_path
                }
            ] if cfg.use_custom_svg_marker else []
        ),

        "layerSources": [
            {
                "id": layer_source_id,
                "name": "starbucks_seattle_geojson",
                "type": "geojson",
                "itemId": lakehouse_id,
                "relativePath": cfg.geojson_relative_path,
                "refreshIntervalMs": 0
            }
        ],

        "layerSettings": [
            {
                "id": layer_setting_id,
                "name": "Starbucks (Seattle)",
                "sourceId": layer_source_id,
                "options": {
                    "type": "vector",
                    "visible": True,
                    "tooltipKeys": ["name"],
                    "pointLayerType": "marker",

                    "markerOptions": (
                        {
                            "iconOptions": {
                                "image": custom_svg_marker,
                                "anchor": "bottom",
                                "opacity": 1.0,
                                "rotation": 0,
                                "allowOverlap": False,
                                "rotationAlignment": "viewport",
                                "pitchAlignment": "viewport"
                            },
                            "icon": icon_source_id
                        }
                        if cfg.use_custom_svg_marker
                        else
                        {
                            "size": 22,
                            "fillColor": "#006241",
                            "strokeColor": "#FFFFFF",
                            "strokeWidth": 2,
                            "icon": cfg.builtin_icon_name_fallback,
                            "iconOptions": {
                                "image": f"{layer_setting_id}:{cfg.builtin_icon_name_fallback}",
                                "anchor": "bottom",
                                "opacity": 1.0,
                                "rotation": 0,
                                "allowOverlap": False,
                                "rotationAlignment": "viewport",
                                "pitchAlignment": "viewport"
                            }
                        }
                    )
                }
            }
        ]
    }

    return map_json

Wskazówka

Porady związane z definicją mapy:

  • Właściwość image używa klucza złożonego w formacie <layerSettingId>:<iconId> , aby odwołać się do ikony warstwy. Powoduje to skojarzenie konfiguracji renderowania znacznika ze źródłem ikony zdefiniowanym wcześniej w definicji mapy.
  • Ustawienie refreshIntervalMs na 0 wyłącza automatyczne odświeżanie. Jest to odpowiednie dla statycznych plików GeoJSON przechowywanych w usłudze Lakehouse.

Utwórz mapę z definicją wbudowaną

create_map tworzy mapę, wysyłając metodą POST złożoną definicję inline, i zwraca identyfikator elementu nowej mapy. W tym samouczku żądanie zawiera pojedynczą część zakodowaną w formacie base64 — map.json opakowaną jako payloadType: "InlineBase64" i zakodowaną za pomocą metody _json_to_b64. map.json Ładunek danych odwołuje się już do źródła danych Lakehouse oraz, jeśli jest obecna, do ikony SVG za pośrednictwem relativePath, więc warstwa jest w pełni skonfigurowana przez wywołanie Create Map bez dodatkowej komunikacji zwrotnej updateDefinition. Jeśli chcesz ustawić niestandardowe metadane elementu lub przypiąć przyjazną dla Git logicalId, dodaj część .platform do tej samej tablicy parts; Fabric stosuje domyślne metadane, gdy pominie się .platform, co właśnie robi ten samouczek.

Interfejs API REST tworzenia mapy może odpowiedzieć za pomocą 201 Created (synchronicznego, wbudowanego identyfikatora), 202 Accepted (asynchronicznego LRO za pośrednictwem Location lub x-ms-operation-id), lub 200 OK z ładunkiem uzupełniania tylko do stanu, w którym mapa nie jest jeszcze widoczna w mapach listy z powodu opóźnienia propagacji zaplecza. _handle_lro obejmuje wszystkie te przypadki — w tym tworzenie listy i dopasowywanie według displayName — dlatego ta funkcja przekazuje jej pełną obsługę odpowiedzi w jednym wywołaniu.

Aby uzyskać więcej informacji, zobacz Definicja elementu mapy.

Dodaj następujące elementy po build_map_json funkcji:

# =========================================================
# Step 5: Create a map with inline definition
# =========================================================

def create_map(client: httpx.Client, fabric: FabricClient, cfg: Config, map_json: dict) -> str:
    """
    Create the Fabric map with its definition inline and return its item ID.

    Sends a single Create map request whose `parts` array carries one
    base64-encoded payload, `map.json`. The map definition already
    references the Lakehouse data source (and, when present, the SVG
    icon) by `relativePath`, so the layer is wired by the Create Map
    call without a follow-up update. Delegates response handling to
    `_handle_lro`, which covers synchronous, asynchronous, and
    status-only completions.
    """
    create_map_url = f"https://api.fabric.microsoft.com/v1/workspaces/{cfg.workspace_id}/maps"

    create_map_payload = {
        "displayName": cfg.map_display_name,
        "description": cfg.map_description,
        "definition": {
            "parts": [
                {
                    "path": "map.json",
                    "payload": _json_to_b64(map_json),
                    "payloadType": "InlineBase64"
                }
            ]
        }
    }

    map_resp = fabric.request("POST", create_map_url, json_body=create_map_payload)

    return _handle_lro(
        client, map_resp,
        list_url=create_map_url,
        match_display_name=cfg.map_display_name,
    )

Organizowanie przepływu pracy

main to jedyny punkt wejścia, który uruchamia samouczek od początku do końca. Tworzy instancję Config, otwiera jedno httpx.Client, które jest ponownie używane we wszystkich funkcjach pomocniczych, opakowuje je w FabricClient, a następnie wywołuje każdą funkcję etapową zgodnie z kolejnością zależności: create_lakehouse → upload_geojson (zapisuje plik GeoJSON do usługi OneLake w nowym Lakehouse) → upload_svg_marker (opcjonalnie; jest uruchamiana tylko wtedy, gdy ustawiono cfg.use_custom_svg_marker) → build_map_json → create_map.

Kolejność ma znaczenie, ponieważ każdy krok korzysta z czegoś utworzonego przez wcześniejszy krok — upload_geojson i upload_svg_marker potrzebują identyfikatora elementu Lakehouse, a build_map_json odwołuje się do obu elementów przesłanych przez relativePath, dzięki czemu opcja Utwórz mapę może je rozwiązać podczas renderowania. Ostatni blok print wyświetla identyfikator usługi Lakehouse, identyfikator map oraz ścieżki względne przesłanych zasobów, dzięki czemu można je znaleźć w portalu Fabric.

Dodaj następujące elementy po create_map funkcji:

# =========================================================
# main(): orchestrates the full workflow
# =========================================================

def main():
    """
    Orchestrate the tutorial workflow.

    1) Create a Lakehouse
    2) Upload GeoJSON to the Lakehouse
    3) Upload a custom SVG marker (optional)
    4) Build the map definition (map.json)
    5) Create the map with its definition inline
    """
    cfg = Config()

    print("Initializing clients...")
    with httpx.Client(timeout=60) as client:
        fabric = FabricClient(client)

        # Step 1
        lakehouse_id = create_lakehouse(client, fabric, cfg)

        # Step 2
        upload_geojson(cfg, lakehouse_id)

        # Step 3 (optional)
        upload_svg_marker(cfg, lakehouse_id)

        # Step 4
        map_json = build_map_json(cfg, lakehouse_id)

        # Step 5
        map_id = create_map(client, fabric, cfg, map_json)

        print("\nDONE")
        print("Lakehouse ID:", lakehouse_id)
        print("Map ID:", map_id)
        print("GeoJSON layer path:", cfg.geojson_relative_path)
        if cfg.use_custom_svg_marker:
            print("Custom SVG marker path:", cfg.svg_relative_path)


if __name__ == "__main__":
    main()

W tym momencie zdefiniowano całą konfigurację i kod.

W następnym kroku uruchomisz skrypt, aby utworzyć usługę Lakehouse, przekazać dane i wygenerować mapę.

Uruchamianie aplikacji

Note

Nazwy wyświetlane elementów Lakehouse i map muszą być unikatowe w obrębie obszaru roboczego. Przed ponownym uruchomieniem skryptu usuń elementy utworzone w poprzednim uruchomieniu z obszaru roboczego Fabric lub zmień lakehouse_display_name / map_display_name w Config. W przeciwnym razie wywołania create kończą się błędem 409 ItemDisplayNameAlreadyInUse.

Uruchom skrypt:

python create_map_from_geojson.py

Jeśli skrypt zostanie uruchomiony pomyślnie, zobaczysz dane wyjściowe podobne do następujących:

DONE
Lakehouse ID: <Lakehouse ID>
Map ID: <Map ID>
GeoJSON layer path: Files/vector/starbucks-seattle.geojson
Custom SVG marker path: Files/icons/starbucks-marker.svg

W usłudze Microsoft Fabric mapa powinna wyglądać mniej więcej tak:

Zrzut ekranu mapy usługi Microsoft Fabric przedstawiający Seattle z wieloma zielonymi ikonami znaczników Starbucks, skupionymi w centrum miasta. Mapa przedstawia ulice i akweny z jasnoszarym tłem. Na panelu Warstwy danych po lewej stronie jest wyświetlana warstwa Starbucks dla Seattle. Mapa skupia się na centrum Seattle, w tym na nabrzeżu Elliott Bay, ze znacznikami wskazującymi poszczególne lokalizacje Starbucks, wskazane w pliku GeoJSON dołączonym do samouczka.

Wskazówka

Jeśli mapa nie pojawi się od razu, odśwież obszar roboczy lub zaczekaj kilka sekund, aż zakończy się propagacja zmian po stronie backendu.

Podsumowanie

W tym samouczku udało Ci się utworzyć zautomatyzowane rozwiązanie geoprzestrzenne przy użyciu usługi Microsoft Fabric Maps i danych z usługi Lakehouse.

Użyto interfejsów API REST Fabric i Python do aprowizowania i konfigurowania wszystkich wymaganych zasobów, a następnie wizualizowania danych przestrzennych przechowywanych w usłudze OneLake.

Wykonano następujące czynności:

  • Przesłano dane przestrzenne do Lakehouse
  • Skonfigurowano zestaw danych na potrzeby wizualizacji geoprzestrzennej
  • Utworzono mapę Fabric z definicją śródliniową
  • Połączono mapę z danymi usługi Lakehouse
  • Skonfigurowane warstwy mapy do renderowania funkcji przestrzennych

Ta architektura przedstawia typowy wzorzec analizy wsadowej i historycznej analizy przestrzennej w Fabric:

  • Dane są przechowywane w usłudze OneLake (Lakehouse)
  • Mapuje zapytania i renderuj zestawy danych przestrzennych
  • Warstwy zapewniają wizualny wgląd w dane geograficzne

Automatyzując tworzenie zasobów przy użyciu interfejsów API Python i REST, masz teraz powtarzalne podejście do tworzenia aplikacji geoprzestrzennych na podstawie statycznych lub historycznych zestawów danych.

Następne kroki

Teraz, gdy już wiesz, jak wizualizować dane przestrzenne z usługi Lakehouse, możesz rozszerzyć to rozwiązanie:

  • Łączenie wielu zestawów danych w celu uzyskania bardziej rozbudowanej analizy geoprzestrzennej
  • Stosowanie stylów i filtrowania w celu wyróżnienia trendów i wzorców
  • Dodawanie warstw odwołań, takich jak granice lub trasy
  • Automatyczne integrowanie potoków danych w celu automatycznego odświeżania zestawów danych
  • Eksplorowanie scenariuszy przesyłania strumieniowego w czasie rzeczywistym przy użyciu usługi Eventstream i Eventhouse

Aby uzyskać więcej informacji na temat pracy z danymi przestrzennymi i mapami w Fabric, zobacz:

Omówienie usługi Fabric Maps

Tworzenie mapy w Fabric

Aby zapoznać się z samouczkiem przedstawiającym tworzenie mapy w czasie rzeczywistym przy użyciu interfejsów API REST, zobacz:

Tutorial: tworzenie mapy w czasie rzeczywistym przy użyciu interfejsów API REST i Python

  • Last updated on