API-proxy létrehozása GeoCataloghoz az Azure API Management használatával

Ez a cikk végigvezeti az Azure API Management (APIM) API-proxyként való beállításán a Microsoft Planetary Computer Pro GeoCatalog előtt. Ezzel a konfigurációval a következőt teheti:

  • Névtelen hozzáférés engedélyezése: a hívóknak nincs szükségük saját Microsoft Entra-hitelesítő adataikra. Az APIM felügyelt identitás használatával hitelesíti a GeoCatalogot a nevükben.
  • Nem Entra-hitelesítés: a hívók támogathatják a nem Entra-alapú hitelesítési módszereket. Az APIM felügyelt identitás használatával hitelesíti a GeoCatalogot a nevükben.
  • Gyűjteményszintű hozzáférés-vezérlés kényszerítése: korlátozza, hogy mely Spatiotemporal Access Catalog (STAC) gyűjtemények láthatók a proxyn keresztül, annak ellenére, hogy a GeoCatalogs natív módon nem támogatja a gyűjteményszintű szerepköralapú hozzáférés-vezérlést (RBAC).

Az alábbi ábra az APIM-proxy hozzáadása előtti és utáni architektúrát mutatja be:

Előtt Minden hívó közvetlenül hitelesíti a GeoCatalogot:

caller ──(Entra token)──► GeoCatalog

Után Az APIM a hívók és a GeoCatalog között helyezkedik el, és kezeli a hitelesítést és a hozzáférés-vezérlést:

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

Prerequisites

Felügyelt identitás hozzárendelése az APIM-hez

Ahhoz, hogy az APIM hitelesíthesse magát a GeoCatalogban, társítania kell a felhasználó által hozzárendelt felügyelt identitást az APIM-példánysal.

  1. Az Azure Portalon keresse meg az API Management-példányt.
  2. Válassza az Identitás lehetőséget a bal oldali oldalsávon.
  3. Válassza a Felhasználó által hozzárendelt lapot.
  4. Válassza a Hozzáadás lehetőséget, majd válassza ki azt a felhasználó által hozzárendelt felügyelt identitást, amelynek GeoCatalog-olvasó szerepköre van a GeoCatalogon.
  5. A megerősítéshez válassza a Hozzáadás lehetőséget.

Az API létrehozása az APIM-ben

Definiáljon egy új API-t az APIM-ben, amely a GeoCatalog-háttérrendszernek küldi a kéréseket.

  1. Az APIM-példányban válassza az API-kat a bal oldali oldalsávon.

  2. Válassza a + API hozzáadása>HTTP lehetőséget.

  3. Konfigurálja az API-t a következő beállításokkal:

    Setting Érték
    Megjelenített név Leíró név (például GeoCatalog API)
    A webszolgáltatás URL-címe A GeoCatalog-végpont (például https://<name>.<id>.<region>.geocatalog.spatio.azure.com)
    URL-séma HTTPS
    API URL-címének utótagja Hagyja üresen (gyökérútvonal)
    Előfizetés szükséges Nem, névtelen hozzáféréshez; Igen, előfizetési kulcsalapú hozzáférés esetén

  4. Válassza a Create gombot.

API-műveletek definiálása

Adja hozzá a következő műveleteket a GeoCatalog API felületének megfelelően. A helyettesítő (/*) műveletek minden egyező kérést továbbítanak a háttérrendszernek. Az explicit gyűjtési műveletek lehetővé teszik, hogy később gyűjteményspecifikus szabályzatokat alkalmazzon a hozzáférés-vezérléshez.

Megjelenített név Módszer URL-sablon
GET GET /*
Gyűjteményelemek lekérése GET /stac/collections/{collection_id}/items
Egyetlen gyűjtemény lekérése GET /stac/collections/{collection_id}
Gyűjtemény-alerőforrások lekérése GET /stac/collections/{collection_id}/*
poszt poszt /*

Az egyes műveletek hozzáadása:

  1. Válassza ki a létrehozott API-t.
  2. Válassza a + Művelet hozzáadása menüpontot.
  3. Adja meg az előző táblázat Megjelenítési nevét, metódusát és URL-sablont .
  4. Válassza az Mentésgombot.

Az API-szintű szabályzat konfigurálása

Az API-szintű szabályzat a teljes API hitelesítését és URL-átírását kezeli. Ez a szabályzat jogkivonatot szerez be a felhasználó által hozzárendelt felügyelt identitásból, és minden, a GeoCatalog háttérrendszernek továbbított kéréshez csatolja.

  1. Válassza ki a létrehozott API-t, majd válassza az Összes művelet lehetőséget.
  2. A Bejövő feldolgozás szakaszban válassza a </> (kódszerkesztő) ikont.
  3. Cserélje le a szabályzat tartalmát a következő szabályzatra:
<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>

Cserélje le a következő helyőrzőket:

Placeholder Érték
<managed-identity-client-id> Az APIM-hez hozzárendelt, felhasználó által létrehozott felügyelt identitás ügyfélazonosítója
<name>.<id>.<region> A GeoCatalog-végpont összetevői
<apim-name> Az APIM-példány neve

Az alábbi táblázat az egyes szabályzatelemeket ismerteti:

Szabályzatelem Alkalmazás célja
authentication-managed-identity Jogkivonatot szerez be a célközönség számára a https://geocatalog.spatio.azure.com megadott felügyelt identitás használatával, és csatolja azt a kimenő kéréshez.
set-header (törlés Accept-Encoding) Eltávolítja a fejlécet a Accept-Encoding bejövő kérelmekből. Lásd Miért távolítsa el az Accept-Encoding.
find-and-replace A GeoCatalog háttérrendszer URL-címét a választörzsekben az APIM átjáró URL-címére írja át. Átírás nélkül a STAC-hivatkozások (self, root, parent, stb.) hozzáférhetővé teszik a háttéri URL-címet a hívók számára.

Miért távolítsuk el az Accept-Encoding-et

A kliensek, mint például a Python requests és httpx, alapértelmezés szerint Accept-Encoding: gzip, deflate küldenek. Amikor a háttérrendszer megkapja ezt a fejlécet, tömörített választ ad vissza. Az APIM kimenő szabályzatai, mint például find-and-replace, a nyers válasz törzsén működnek, és nem tudják kicsomagolni, ezért észrevétlenül nem tesznek semmit. A fejléc eltávolításával a háttérrendszer egy tömörítetlen választ ad vissza, amelyet a kimenő szabályok feldolgozhatnak.

Note

curl és wget ne küldjön Accept-Encoding alapértelmezés szerint. Ez azt jelenti, hogy a kimenő szabályzatok megfelelően működnek, amikor ezekkel az eszközökkel teszteli őket. Az inkonzisztencia csak azoknál az ügyfeleknél jelentkezik, akik tömörítést kérnek.

Gyűjteményszintű hozzáférés-vezérlés kényszerítése

A GeoCatalog alapértelmezés szerint minden gyűjteményét elérhetővé teszi bármely hitelesített hívó számára. Ha korlátozni szeretné, hogy mely gyűjtemények láthatók az APIM-on keresztül, alkalmazzon olyan műveleti szintű szabályzatokat, amelyek blokkolják a széles körű STAC-felderítést, és engedélyezési listát kényszerítenek ki.

Az engedélyezett gyűjtemények meghatározása

Hozzon létre egy elnevezett értéket az APIM-ben az engedélyezett gyűjteményazonosítók listájának tárolásához:

  1. Az APIM-példányban válassza az Elnevezett értékeket a bal oldali oldalsávon.
  2. Válassza ki a -t, és adja hozzá a-et.
  3. Állítsa be a nevet a következőreallowed-collections: .
  4. Állítsa be az Értéket a megengedett gyűjteményazonosítók vesszővel tagolt listájára (például sentinel-2-l2a,landsat-8-c2-l2).
  5. Válassza az Mentésgombot.

A kezdőlap és a gyűjtemények listájának letiltása

Tiltsa le a katalógus összes gyűjteményét megjelenítő útvonalakat. Adja hozzá a következő műveleteket, és csatoljon egy szabályzatot, amely azonnal visszaküldi 404.

Megjelenített név Módszer URL-sablon
Gyökér blokkolása GET /
Gyűjtemények blokkolása GET /stac/collections

Alkalmazza a következő műveletszintű szabályzatot mindkét műveletre:

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

A STAC-végpont /stac/search egy paramétert collections fogad el – lekérdezési sztringként a GET-en vagy a POST JSON-törzsében. Védőkorlátok nélkül a hívó a katalógus összes gyűjteményében kereshet. Az alábbi szabályzatok ellenőrzik, hogy csak az engedélyezett készletből származó gyűjtemények kérve vannak-e.

Két művelet hozzáadása:

Megjelenített név Módszer URL-sablon
GET keresés GET /stac/search
POST-keresés poszt /stac/search

GET /stac/keresési szabályzat

Ez a szabályzat ellenőrzi a lekérdezési paramétert collections . Minden vesszővel elválasztott értéknek az engedélyezett csoportban kell lennie. A paraméter nélküli collections kérelmeket a rendszer elutasítja a következővel 403 Forbidden: .

Alkalmazza a következő szabályzatot a GET keresési műveletre:

<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

Az APIM-szabályzatkifejezések korlátozott C# környezetben futnak. Használja condition='@{...}' az (egy idézőjeles) attribútumot, hogy a kettős idézőjelek a kifejezésen belül működhessenek. Kerülje az általános típusparamétereket (például GetValueOrDefault<string>) és a LINQ lambdákat – használjon explicit típuskonverziókat és foreach hurkokat.

POST /stac/keresési szabályzat

Ez a szabályzat elemzi a JSON-törzset, és ellenőrzi a tömböt collections . A paraméter nélküli collections kérelmeket a rendszer elutasítja a következővel 403 Forbidden: .

Alkalmazza a következő szabályzatot a POST keresési műveletre:

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

Engedélyezett gyűjtemények alkalmazása a gyűjteményvégpontokon

Explicit műveletek nélkül a GET /stac/collections/sentinel-2-l2a vagy GET /stac/collections/sentinel-2-l2a/items jellegű kérések átterelődnek a GET /* helyettesítő karakterhez, és gyűjteményszintű ellenőrzés nélkül érik el a háttérrendszert. Alkalmazza az elérési útparaméter-szabályzatot, amely érvényesíti a collection_id a {{allowed-collections}}-tal szemben, az alábbi, a API-műveletek definiálása során létrehozott műveletekre:

Megjelenített név Módszer URL-sablon
Egyetlen gyűjtemény lekérése GET /stac/collections/{collection_id}
Gyűjtemény-alerőforrások lekérése GET /stac/collections/{collection_id}/*
Gyűjteményelemek lekérése GET /stac/collections/{collection_id}/items

Alkalmazza a következő szabályzatot mindhárom műveletre:

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

Az engedélyezett gyűjtemények alkalmazása a SAS jogkivonat útvonalain

A GeoCatalog SAS API lehetővé teszi, hogy a hívók tárjogkivonatokat hozzanak létre, és aláírják az objektum HREF-eit. Korlátozások nélkül a hívó bármilyen gyűjteményhez tokeneket szerezhet be. Az alábbi szabályzatok biztosítják, hogy csak az engedélyezett gyűjtemények férhessenek hozzá.

Adja hozzá a következő műveleteket:

Megjelenített név Módszer URL-sablon
SAS-jogkivonat lekérése GET /sas/token/{collection_id}
SAS jel blokkolása GET /sas/sign

Alkalmazza a blokkolási 404 szabályzatot (ugyanaz, mint a gyökér- és gyűjteményblokk) a SAS aláírás blokkolása műveletre. A hívóknak ehelyett gyűjteményszintű SAS-jogkivonatokat kell /sas/token/{collection_id} beszerezniük.

Alkalmazza a következő szabályzatot a GET SAS-jogkivonat-műveletre :

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

Engedélyezett gyűjtemények szabályainak betartatása az adatútvonalakon

A /data/mosaic/ végpontok csempézési renderelést, határolókeret-kivágásokat és keresési regisztrációt biztosítanak. Két házirendcsoportra van szükség:

  1. Keresés regisztrálása – ellenőrizze a collections tömböt a JSON-törzsben.
  2. Minden más gyűjtőútvonal – érvényesítse az elérési út paramétert collectionId.

Adja hozzá a következő műveleteket:

Megjelenített név Módszer URL-sablon
POST regisztrálási keresés poszt /data/mosaic/register
GET adatgyűjtés GET /data/mosaic/collections/{collectionId}/*

POST /data/mozaik/regisztrációs szabályzat

Ez a szabályzat ellenőrzi a collections JSON törzs tömböt az engedélyezett készlettel szemben. A paraméter nélküli collections kérelmeket a rendszer elutasítja.

<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/mozaik/collections/{collectionId}/* szabályzat

Ez a szabályzat hitelesíti az collectionId elérési út paraméterét az engedélyezett halmazhoz viszonyítva. Alkalmazza ezt a szabályzatot a GET adatgyűjtési műveletekre is.

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

Gyakori kérdések

Hogyan frissíthetem az engedélyezett gyűjtemények listáját?

Szerkessze a allowed-collections névvel ellátott értéket az APIM-példányban. Nincs szükség szabályzatmódosításra.

Mi történik, ha egy hívó kihagyja a gyűjtemények paraméterét?

A kérést a rendszer elutasítja a következővel 403 Forbidden: . A hívóknak mindig meg kell adniuk, hogy mely gyűjteményekben szeretnének keresni.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: