Tworzenie serwera proxy interfejsu API dla usługi GeoCatalog przy użyciu usługi Azure API Management

Ten artykuł przeprowadzi Cię przez proces konfigurowania usługi Azure API Management (APIM) jako serwera proxy interfejsu API dla Microsoft Planetary Computer Pro GeoCatalog. Za pomocą tej konfiguracji można wykonywać następujące czynności:

Włącz dostęp anonimowy: osoby wywołujące nie potrzebują własnych poświadczeń firmy Microsoft Entra. Usługa APIM uwierzytelnia się w GeoCatalogu w ich imieniu przy użyciu tożsamości zarządzanej.
Uwierzytelnianie inne niż Entra: osoby wywołujące mogą obsługiwać metody uwierzytelniania nienależące do entra. Usługa APIM uwierzytelnia się w usłudze GeoCatalog w ich imieniu przy użyciu tożsamości zarządzanej.
Wymuszanie kontroli dostępu na poziomie kolekcji: ogranicz, które kolekcje Katalogu Dostępu Spacjotemporalnego (STAC) są widoczne za pośrednictwem serwera proxy, mimo że GeoCatalogs nie obsługują w sposób natywny kontroli dostępu opartej na rolach (RBAC) na poziomie kolekcji.

Na poniższym diagramie przedstawiono architekturę przed i po dodaniu serwera proxy usługi APIM:

Przed Każdy użytkownik uwierzytelnia się bezpośrednio do GeoCatalog:

caller ──(Entra token)──► GeoCatalog

Po APIM znajduje się między obiektami wywołującymi a GeoCatalog, aby obsługiwać uwierzytelnianie i kontrolę dostępu:

caller ──(anonymous / APIM Subscription Keys)──► APIM ──(managed identity token)──► GeoCatalog

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz bezpłatne konto.
Istniejący zasób GeoCatalog.
Wystąpienie usługi Azure API Management.
Tożsamość zarządzana przypisana przez użytkownika przypisana do wystąpienia usługi APIM z przypisaniem roli GeoCatalog Reader nad zasobem GeoCatalog. Zobacz Zarządzanie dostępem , aby uzyskać instrukcje dotyczące przypisywania ról.

Przypisz tożsamość zarządzaną do APIM

Zanim usługa APIM będzie mogła uwierzytelnić w usłudze GeoCatalog, należy skojarzyć tożsamość zarządzaną przypisaną przez użytkownika z wystąpieniem usługi APIM.

Na portalu Azure przejdź do instancji zarządzania API.
Wybierz Tożsamość z lewego paska bocznego.
Wybierz kartę Użytkownik przypisany .
Wybierz pozycję Dodaj, a następnie wybierz nadaną przez użytkownika tożsamość zarządzaną, która ma rolę Czytelnika GeoCatalog na Twoim GeoCatalog.
Wybierz pozycję Dodaj , aby potwierdzić.

Tworzenie interfejsu API w usłudze APIM

Zdefiniuj nowy interfejs API w APIM, który działa jako serwer proxy, wysyłając żądania do backendu GeoCatalog.

W wystąpieniu usługi APIM wybierz pozycję Interfejsy API na lewym pasku bocznym.
Wybierz + Dodaj interfejs API>HTTP.

Skonfiguruj interfejs API przy użyciu następujących ustawień:

Setting	Wartość
Nazwa wyświetlana	Nazwa opisowa (na przykład `GeoCatalog API`)
Adres URL usługi sieci Web	Punkt końcowy geokatalogu (na przykład `https://<name>.<id>.<region>.geocatalog.spatio.azure.com`)
Schemat adresu URL	HTTPS
Końcówka adresu URL API	Pozostaw puste (ścieżka główna)
Wymagana subskrypcja	Nie, w przypadku dostępu anonimowego; Tak, w przypadku dostępu opartego na kluczu subskrypcji

Wybierz Utwórz.

Definiowanie operacji interfejsu API

Dodaj następujące operacje, aby dopasować powierzchnię interfejsu API GeoCatalog. Operacje z symbolami wieloznacznymi (/*) przekazują wszystkie pasujące żądania do serwera. Operacje jawnego zbierania umożliwiają późniejsze stosowanie zasad specyficznych dla kolekcji na potrzeby kontroli dostępu.

nazwa wyświetlana	Metoda	Szablon adresu URL
GET	GET	`/*`
Pobierz elementy kolekcji	GET	`/stac/collections/{collection_id}/items`
Pobierz pojedynczą kolekcję	GET	`/stac/collections/{collection_id}`
Pobieranie zasobów podrzędnych kolekcji	GET	`/stac/collections/{collection_id}/*`
POST	POST	`/*`

Aby dodać każdą z operacji:

Wybierz utworzony interfejs API.
Wybierz pozycję + Dodaj operację.
Wprowadź szablon Nazwa wyświetlana, Metoda i Adres URL z poprzedniej tabeli.
Wybierz opcję Zapisz.

Konfigurowanie zasad na poziomie interfejsu API

Zasady na poziomie interfejsu API obsługują uwierzytelnianie i ponowne zapisywanie adresów URL dla całego interfejsu API. Ta zasada uzyskuje token z tożsamości zarządzanej przypisanej przez użytkownika i dołącza go do każdego żądania przekazanego do zaplecza GeoCatalog.

Wybierz utworzony interfejs API, a następnie wybierz pozycję Wszystkie operacje.
W sekcji Przetwarzanie przychodzące wybierz ikonę </> (edytor kodu).
Zastąp zawartość zasad następującymi zasadami:

<policies>
    <inbound>
        <base />
        <authentication-managed-identity
            resource="https://geocatalog.spatio.azure.com"
            client-id="<managed-identity-client-id>" />
        <set-header name="Accept-Encoding"
            exists-action="delete" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
        <find-and-replace
            from="https://<name>.<id>.<region>.geocatalog.spatio.azure.com"
            to="https://<apim-name>.azure-api.net" />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Zastąp następujące symbole zastępcze:

Placeholder	Wartość
`<managed-identity-client-id>`	Identyfikator klienta tożsamości zarządzanej przypisanej przez użytkownika do APIM
`<name>.<id>.<region>`	Składniki endpointu GeoCatalog
`<apim-name>`	Nazwa wystąpienia usługi APIM

W poniższej tabeli opisano każdy element zasad:

Element zasad	Purpose
`authentication-managed-identity`	Uzyskuje token dla odbiorcy `https://geocatalog.spatio.azure.com` za pomocą określonej tożsamości zarządzanej i dołącza go do żądania wychodzącego.
`set-header` (usuń `Accept-Encoding`)	Usuwa nagłówek `Accept-Encoding` z żądań przychodzących. Zobacz Dlaczego usuwanie Accept-Encoding.
`find-and-replace`	Ponownie zapisz adres URL zaplecza geocatalogu w treści odpowiedzi na adres URL bramy usługi APIM. Bez tego ponownego zapisywania linki STAC (`self`, `root`, `parent`i tak dalej) uwidaczniają adres URL zaplecza obiektom wywołującym.

Dlaczego usuwać Accept-Encoding

Klienci, takie jak Python requests i httpx, domyślnie wysyłają Accept-Encoding: gzip, deflate. Gdy zaplecze odbiera ten nagłówek, zwraca skompresowaną odpowiedź. Zasady ruchu wychodzącego usługi APIM, takie jak find-and-replace, działają na nieprzetworzonej treści odpowiedzi i nie mogą jej dekompresować, więc dyskretnie nic nie wykonują. Usunięcie nagłówka powoduje, że zaplecze zwraca nieskompresowaną odpowiedź, którą mogą przetwarzać polityki wychodzące.

Note

curl i wget nie wysyłają Accept-Encoding domyślnie. Oznacza to, że polityki wychodzące wydają się działać prawidłowo podczas testowania z użyciem tych narzędzi. Niespójność dotyczy tylko klientów żądających kompresji.

Wymuszanie kontroli dostępu na poziomie kolekcji

Domyślnie geocatalog uwidacznia wszystkie swoje kolekcje dla dowolnego uwierzytelnionego wywołującego. Aby ograniczyć, które kolekcje są widoczne za pomocą usługi APIM, zastosuj zasady na poziomie operacyjnym, które blokują szerokie wyszukiwanie STAC i wymuszają użycie listy dozwolonych.

Definiowanie dozwolonych kolekcji

Utwórz nazwaną wartość w usłudze APIM, aby przechowywać listę dozwolonych identyfikatorów kolekcji:

W wystąpieniu usługi APIM wybierz pozycję Nazwane wartości na lewym pasku bocznym.
Wybierz + Dodaj.
Ustaw wartość Nazwa na allowed-collections.
Ustaw Wartość na listę dozwolonych identyfikatorów kolekcji rozdzielonych przecinkami (na przykład sentinel-2-l2a,landsat-8-c2-l2).
Wybierz opcję Zapisz.

Zablokuj stronę docelową i listę kolekcji

Blokuj ścieżki, które odsłaniają każdą kolekcję w wykazie. Dodaj następujące operacje i dołącz politykę, która zwraca 404 natychmiast.

nazwa wyświetlana	Metoda	Szablon adresu URL
Blokuj root	GET	`/`
Blokuj kolekcje	GET	`/stac/collections`

Zastosuj następujące zasady na poziomie operacji do obu operacji:

<policies>
    <inbound>
        <base />
        <return-response>
            <set-status code="404" reason="Not Found" />
        </return-response>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Wymuszanie dozwolonych kolekcji w wyszukiwaniu STAC

Punkt końcowy STAC /stac/search akceptuje collections parametr — jako ciąg zapytania w pliku GET lub w treści JSON w usłudze POST. Bez barier zabezpieczających obiekt wywołujący może przeszukiwać każdą kolekcję w katalogu. Następujące zasady sprawdzają, czy żądane są tylko kolekcje z dozwolonego zestawu.

Dodaj dwie operacje:

nazwa wyświetlana	Metoda	Szablon adresu URL
Wyszukiwanie GET	GET	`/stac/search`
Wyszukiwanie POST	POST	`/stac/search`

GET /stac/search policy

Ta zasada weryfikuje collections parametr zapytania. Każda wartość rozdzielona przecinkami musi znajdować się w dozwolonym zestawie. Żądania bez parametru collections są odrzucane z powodu 403 Forbidden.

Zastosuj następujące zasady do operacji wyszukiwania GET :

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var raw = context.Request.Url.Query
                    .GetValueOrDefault("collections", "");
                if (string.IsNullOrWhiteSpace(raw)) {
                    return true;
                }
                foreach (var c in raw.ToLower().Split(
                    new [] { "," },
                    StringSplitOptions.RemoveEmptyEntries))
                {
                    if (!c.Trim().Equals(allowed)) {
                        return true;
                    }
                }
                return false;
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Note

Wyrażenia zasad usługi APIM są uruchamiane w ograniczonym środowisku języka C#. Użyj condition='@{...}' (atrybut z pojedynczym cudzysłowem), aby cudzysłowy były poprawnie interpretowane wewnątrz wyrażenia. Unikaj ogólnych parametrów typu (na przykład GetValueOrDefault<string>) oraz lambd LINQ – używaj zamiast tego jawnych rzutów i pętli foreach.

POST /stac/search policy

Ta zasada parsuje treść JSON i weryfikuje tablicę collections. Żądania bez parametru collections są odrzucane z użyciem 403 Forbidden polecenia.

Zastosuj następujące zasady do operacji wyszukiwania POST :

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <set-variable name="requestBody"
            value="@(context.Request.Body
                .As&lt;string&gt;(
                    preserveContent: true))" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var body = (string)context
                    .Variables["requestBody"];
                var json = Newtonsoft.Json.Linq
                    .JObject.Parse(body);
                var arr = json["collections"]
                    as Newtonsoft.Json.Linq.JArray;
                if (arr == null || arr.Count == 0) {
                    return true;
                }
                foreach (var token in arr) {
                    if (!token.ToString().Trim()
                        .ToLower().Equals(allowed))
                    {
                        return true;
                    }
                }
                return false;
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Wymuszanie dozwolonych zbiorów na punktach końcowych kolekcji

Bez jawnych operacji, żądania takie jak GET /stac/collections/sentinel-2-l2a lub GET /stac/collections/sentinel-2-l2a/items przechodzą do symbolu GET /* wieloznacznego i docierają do zaplecza bez sprawdzania na poziomie kolekcji. Zastosuj politykę parametrów ścieżki, która weryfikuje collection_id w stosunku do {{allowed-collections}} do następujących operacji, które utworzyłeś w Definiowanie operacji interfejsu API:

nazwa wyświetlana	Metoda	Szablon adresu URL
Pobierz pojedynczą kolekcję	GET	`/stac/collections/{collection_id}`
Pobieranie podzasobów kolekcji	GET	`/stac/collections/{collection_id}/*`
Pobierz elementy kolekcji	GET	`/stac/collections/{collection_id}/items`

Zastosuj następujące zasady do wszystkich trzech operacji:

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var collectionId = (string)context
                    .Request.MatchedParameters[
                        "collection_id"];
                return !collectionId.Trim()
                    .ToLower().Equals(allowed);
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Wymuszanie dozwolonych kolekcji na ścieżkach tokenu SAS

API GeoCatalog SAS pozwala użytkownikom generować tokeny magazynowe i podpisywać zasoby HREF. Bez ograniczeń wywołujący mógłby uzyskać tokeny dla dowolnej kolekcji. Poniższe zasady zapewniają dostęp tylko do dozwolonych kolekcji.

Dodaj następujące operacje:

nazwa wyświetlana	Metoda	Szablon adresu URL
Uzyskaj token SAS	GET	`/sas/token/{collection_id}`
Blokuj podpis SAS	GET	`/sas/sign`

404 Zastosuj zasady blokowania (takie same jak blok główny i kolekcje) do operacji blokowania sygnatur dostępu współdzielonego. Zamiast tego wywołujący powinni uzyskiwać /sas/token/{collection_id} tokeny SAS na poziomie kolekcji.

Zastosuj następujące zasady do operacji tokenu GET SAS :

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var collectionId = (string)context
                    .Request.MatchedParameters[
                        "collection_id"];
                return !collectionId.Trim()
                    .ToLower().Equals(allowed);
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Egzekwowanie dozwolonych kolekcji na ścieżkach danych

Punkty /data/mosaic/ końcowe zapewniają renderowanie kafelków, przycinanie ramek ograniczających i rejestrację wyszukiwania. Potrzebne są dwie grupy zasad:

Wyszukiwanie w rejestrze — zweryfikuj tablicę collections w treści JSON.
Wszystkie inne ścieżki zbierania — zweryfikuj parametr ścieżki collectionId.

Dodaj następujące operacje:

nazwa wyświetlana	Metoda	Szablon adresu URL
Wyszukiwanie w rejestrze POST	POST	`/data/mosaic/register`
Zbieranie danych GET	GET	`/data/mosaic/collections/{collectionId}/*`

POST /data/mozaika/zasady rejestracji

Te zasady weryfikują tablicę collections w treści JSON względem dozwolonego zestawu. Żądania bez parametru collections są odrzucane.

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <set-variable name="requestBody"
            value="@(context.Request.Body
                .As&lt;string&gt;(
                    preserveContent: true))" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var body = (string)context
                    .Variables["requestBody"];
                var json = Newtonsoft.Json.Linq
                    .JObject.Parse(body);
                var arr = json["collections"]
                    as Newtonsoft.Json.Linq.JArray;
                if (arr == null || arr.Count == 0) {
                    return true;
                }
                foreach (var token in arr) {
                    if (!token.ToString().Trim()
                        .ToLower().Equals(allowed))
                    {
                        return true;
                    }
                }
                return false;
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

GET /data/mozaika/kolekcje/{collectionId}/* polityka

Ta zasada sprawdza, czy parametr ścieżki collectionId znajduje się w dozwolonym zestawie. Zastosuj te zasady do obu operacji zbierania danych GET .

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var collectionId = (string)context
                    .Request.MatchedParameters[
                        "collectionId"];
                return !collectionId.Trim()
                    .ToLower().Equals(allowed);
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Często zadawane pytania

Jak zaktualizować listę dozwolonych kolekcji?

Edytuj nazwaną allowed-collections wartość w wystąpieniu usługi APIM. Nie są wymagane żadne zmiany zasad.

Co się stanie, jeśli wywołujący pominie parametr kolekcji?

Żądanie zostało odrzucone z 403 Forbidden. Osoby wywołujące muszą zawsze określać, które kolekcje mają być wyszukiwane.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-24