Een API-proxy maken voor een GeoCatalog met behulp van Azure API Management

In dit artikel wordt u begeleid bij het instellen van Azure API Management (APIM) als API-proxy voor een Microsoft Planetary Computer Pro GeoCatalog. Met deze configuratie kunt u het volgende doen:

  • Anonieme toegang inschakelen: bellers hebben geen eigen Microsoft Entra-referenties nodig. APIM verifieert namens hen bij de GeoCatalog met behulp van een beheerde identiteit.
  • Niet-Entra-verificatie: bellers kunnen op niet-Entra gebaseerde verificatiemethoden ondersteunen. APIM wordt namens hen geverifieerd bij GeoCatalog met behulp van een beheerde identiteit.
  • Toegangsbeheer op verzamelingsniveau afdwingen: beperken welke STAC-verzamelingen (Spatiotemporal Access Catalog) zichtbaar zijn via de proxy, ook al bieden GeoCatalogs geen systeemeigen ondersteuning voor op rollen gebaseerd toegangsbeheer op verzamelingsniveau (RBAC).

In het volgende diagram ziet u de architectuur voor en na het toevoegen van de APIM-proxy:

Voordat Elke beller wordt rechtstreeks geverifieerd bij de GeoCatalog:

caller ──(Entra token)──► GeoCatalog

Na APIM bevindt zich tussen aanroepers en geocatalog, afhandeling van verificatie en toegangsbeheer:

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

Prerequisites

De beheerde identiteit toewijzen aan APIM

Voordat APIM zich kan authenticeren bij uw GeoCatalog, moet u de gebruikers-toegewezen beheerde identiteit koppelen aan het APIM-exemplaar.

  1. Blader in Azure Portal naar uw API Management-exemplaar.
  2. Selecteer Identiteit in de linkerzijbalk.
  3. Selecteer het tabblad Vastgestelde gebruiker.
  4. Selecteer Toevoegen en kies vervolgens de door de gebruiker toegewezen beheerde identiteit met de rol GeoCatalog Reader in uw GeoCatalog .
  5. Selecteer Toevoegen om te bevestigen.

De API maken in APIM

Definieer een nieuwe API in APIM die verzoeken doorstuurt naar uw GeoCatalog-achterkant.

  1. Selecteer API's in uw APIM-exemplaar in de linkerzijbalk.

  2. Selecteer + API>HTTP toevoegen.

  3. Configureer de API met de volgende instellingen:

    Configuratie Value
    weergavenaam Een beschrijvende naam (bijvoorbeeld GeoCatalog API)
    URL van webservice Uw GeoCatalog-eindpunt (bijvoorbeeld https://<name>.<id>.<region>.geocatalog.spatio.azure.com)
    URL-schema HTTPS
    API-URL-achtervoegsel Laat leeg (rootpad)
    Abonnement vereist Nee, voor anonieme toegang; Ja, voor toegang op basis van abonnementssleutel

  4. Klik op Creëren.

API-bewerkingen definiëren

Voeg de volgende bewerkingen toe die overeenkomen met het geocatalog-API-oppervlak. De jokertekenbewerkingen (/*) sturen alle overeenkomende aanvragen door naar de back-end. Met de expliciete verzamelingsbewerkingen kunt u later verzamelingsspecifieke beleidsregels toepassen voor toegangsbeheer.

weergavenaam Methode URL-sjabloon
GET GET /*
Verzamelingsitems ophalen GET /stac/collections/{collection_id}/items
Eén verzameling ophalen GET /stac/collections/{collection_id}
Subbronnen voor verzameling ophalen GET /stac/collections/{collection_id}/*
POST POST /*

Elke bewerking toevoegen:

  1. Selecteer de API die u hebt gemaakt.
  2. Selecteer + Bewerking toevoegen.
  3. Voer de weergavenaam, methode en URL-sjabloon uit de voorgaande tabel in.
  4. Selecteer Opslaan.

Het beleid op API-niveau configureren

Het beleid op API-niveau verwerkt verificatie en URL-herschrijven voor de hele API. Dit beleid verkrijgt een token van de door de gebruiker toegewezen beheerde identiteit en koppelt het aan elke aanvraag die wordt doorgestuurd naar de GeoCatalog-back-end.

  1. Selecteer de API die u hebt gemaakt en selecteer vervolgens Alle bewerkingen.
  2. In de sectie Inbound processing, selecteer het pictogram </> (code editor).
  3. Vervang de beleidsinhoud door het volgende beleid:
<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>

Vervang de volgende tijdelijke aanduidingen:

Tijdelijke aanduiding Value
<managed-identity-client-id> De client-id van de door de gebruiker toegewezen beheerde identiteit die is toegewezen aan APIM
<name>.<id>.<region> De onderdelen van het GeoCatalog-eindpunt
<apim-name> De naam van uw APIM-instantie

In de volgende tabel wordt elk beleidselement beschreven:

Beleidselement Purpose
authentication-managed-identity Hiermee verkrijgt u een token voor de https://geocatalog.spatio.azure.com doelgroep met behulp van de opgegeven beheerde identiteit en koppelt u het aan de uitgaande aanvraag.
set-header (verwijderen Accept-Encoding) Hiermee verwijdert u de Accept-Encoding header uit binnenkomende aanvragen. Bekijk Waarom Accept-Encoding strippen.
find-and-replace Herschrijft de back-end-URL van GeoCatalog in antwoordteksten naar de URL van de APIM-gateway. Zonder dit herschrijven maken STAC-koppelingen (self, rootenzovoort parent) de back-end-URL beschikbaar voor bellers.

Waarom Accept-Encoding weglaten

Clients zoals Python requests en httpx verzenden Accept-Encoding: gzip, deflate standaard. Wanneer de back-end deze header ontvangt, wordt er een gecomprimeerd antwoord geretourneerd. Uitgaande APIM-beleidsregels zoals find-and-replace werken op de hoofdtekst van het onbewerkte antwoord en kunnen deze niet decomprimeren, zodat ze niets doen. Door de header te verwijderen, wordt de back-end gedwongen een niet-gecomprimeerd antwoord te geven, dat vervolgens door uitgaande beleidsregels kan worden verwerkt.

Note

curl en wget verzend Accept-Encoding niet standaard. Dit betekent dat uitgaande beleidsregels correct lijken te werken wanneer u met deze hulpprogramma's test. De inconsistentie komt alleen voor bij clients die compressie aanvragen.

Toegangsbeheer op verzamelingsniveau afdwingen

Een GeoCatalog toont standaard alle bijbehorende verzamelingen aan elke geverifieerde beller. Als u wilt beperken welke verzamelingen zichtbaar zijn via APIM, past u beleidsregels op bewerkingsniveau toe die brede STAC-detectie blokkeren en een acceptatielijst afdwingen.

De toegestane verzamelingen definiëren

Maak een benoemde waarde in APIM om de lijst met toegestane verzamelings-id's op te slaan:

  1. Selecteer in uw APIM-exemplaar benoemde waarden in de linkerzijbalk.
  2. Selecteer + Toevoegen.
  3. Stel de naam in op allowed-collections.
  4. Stel de waarde in op een door komma's gescheiden lijst met toegestane verzamelings-id's (bijvoorbeeld sentinel-2-l2a,landsat-8-c2-l2).
  5. Selecteer Opslaan.

De lijst met landingspagina's en verzamelingen blokkeren

Blokkeer de routes waarmee elke verzameling in de catalogus wordt weergegeven. Voeg de volgende bewerkingen toe en koppel een beleid dat onmiddellijk 404 retourneert.

weergavenaam Methode URL-sjabloon
Rootmap blokkeren GET /
Blokverzamelingen GET /stac/collections

Pas het volgende beleid op bewerkingsniveau toe op beide bewerkingen:

<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>

Het STAC-eindpunt /stac/search accepteert een collections parameter, als een querytekenreeks in GET of in de JSON-hoofdtekst op POST. Zonder kaders kan een beller zoeken in elke verzameling in de catalogus. Met het volgende beleid wordt gecontroleerd of alleen verzamelingen uit de toegestane set worden aangevraagd.

Voeg twee bewerkingen toe:

weergavenaam Methode URL-sjabloon
GET zoeken GET /stac/search
POST-zoekopdracht POST /stac/search

GET /stac/search policy

Met dit beleid wordt de collections queryparameter gevalideerd. Elke door komma's gescheiden waarde moet in de toegestane set staan. Aanvragen zonder parameter collections worden geweigerd met 403 Forbidden.

Pas het volgende beleid toe op de GET-zoekbewerking :

<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

APIM-beleidsexpressies worden uitgevoerd in een beperkte C#-omgeving. Gebruik condition='@{...}' (kenmerk met één aanhalingsteken) zodat dubbele aanhalingstekens in de expressie werken. Vermijd algemene typeparameters (bijvoorbeeld GetValueOrDefault<string>) en LINQ lambdas: gebruik in plaats daarvan expliciete casts en foreach lussen.

POST /stac/search-beleid

Dit beleid parseert de JSON-hoofdtekst en valideert de collections matrix. Aanvragen zonder parameter collections worden geweigerd met 403 Forbidden.

Pas het volgende beleid toe op de POST-zoekbewerking :

<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>

Het afdwingen van toegestane verzamelingen op verzamelingseindpunten.

Zonder expliciete bewerkingen vallen aanvragen zoals GET /stac/collections/sentinel-2-l2a of GET /stac/collections/sentinel-2-l2a/items door naar de GET /* wildcard en bereiken de backend zonder controle op collectieniveau. Pas het padparameterbeleid toe dat collection_id valideert tegen {{allowed-collections}} op de volgende bewerkingen die u hebt gemaakt in API-bewerkingen definiëren:

weergavenaam Methode URL-sjabloon
Eén verzameling ophalen GET /stac/collections/{collection_id}
Subbronnen voor verzameling ophalen GET /stac/collections/{collection_id}/*
Verzamelingsitems ophalen GET /stac/collections/{collection_id}/items

Pas het volgende beleid toe op alle drie de bewerkingen:

<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>

Toegestane verzamelingen afdwingen op SAS-tokenroutes

Met de GEOCatalog SAS-API kunnen bellers opslagtokens genereren en HREFs ondertekenen. Zonder beperkingen kan een beller tokens verkrijgen voor elke verzameling. Het volgende beleid zorgt ervoor dat alleen toegestane verzamelingen toegankelijk zijn.

Voeg de volgende bewerkingen toe:

weergavenaam Methode URL-sjabloon
SAS-token OPHALEN GET /sas/token/{collection_id}
SAS-teken blokkeren GET /sas/sign

Pas het 404blokkeringsbeleid (hetzelfde als het root- en verzamelingenblok) toe op de blokkeer SAS-teken operatie. Gebruikers moeten dus /sas/token/{collection_id} gebruiken om SAS-tokens op verzamelingsniveau te verkrijgen.

Pas het volgende beleid toe op de GET SAS-tokenbewerking :

<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>

Het afdwingen van toegestane verzamelingen op dataroutes

De /data/mosaic/ eindpunten bieden tegelweergave, uitsneden van begrenzingsvakken, en zoekopdrachtenregistratie. Er zijn twee beleidsgroepen nodig:

  1. Zoekacties registreren : valideer de collections matrix in de JSON-hoofdtekst.
  2. Alle andere verzamelingsroutes : valideer de collectionId padparameter.

Voeg de volgende bewerkingen toe:

weergavenaam Methode URL-sjabloon
Zoeken in POST-register POST /data/mosaic/register
Gegevensverzameling met GET-verzoek GET /data/mosaic/collections/{collectionId}/*

POST /data/mozaïek/register beleid

Met dit beleid wordt de collections matrix in de JSON-hoofdtekst gevalideerd op basis van de toegestane set. Aanvragen zonder parameter collections worden geweigerd.

<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/mozaïek/collections/{collectionId}/* beleid

Met dit beleid wordt de collectionId padparameter gevalideerd op basis van de toegestane set. Pas dit beleid toe op zowel de GET-gegevensverzamelingsbewerkingen .

<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>

Veelgestelde vragen

Hoe kan ik de lijst met toegestane verzamelingen bijwerken?

Bewerk de allowed-collections benoemde waarde in het APIM-exemplaar. Er zijn geen beleidswijzigingen nodig.

Wat gebeurt er als een aanroeper de parameter verzamelingen weglaat?

De aanvraag wordt geweigerd met 403 Forbidden. Bellers moeten altijd opgeven welke verzamelingen ze willen doorzoeken.

Verwante inhoud

  • Last updated on