Creación de un proxy de API para geocatalog mediante Azure API Management

Este artículo le guía a través de la configuración de Azure API Management (APIM) como proxy de API frente a un Microsoft Planetary Computer Pro GeoCatalog. Con esta configuración puede hacer lo siguiente:

Habilitar el acceso anónimo: los autores de llamadas no necesitan sus propias credenciales de Microsoft Entra. APIM se autentica en GeoCatalog en su nombre mediante una identidad administrada.
Autenticación "no-Entra": los iniciadores de llamadas pueden admitir métodos de autenticación que no se basen en Entra. APIM se autentica en GeoCatalog en su nombre mediante una identidad administrada.
Aplicar el control de acceso de nivel de colección: restrinja qué colecciones del Catálogo de acceso spatiotemporales (STAC) están visibles a través del proxy, aunque GeoCatalogs no admita de forma nativa el control de acceso basado en rol (RBAC) de nivel de colección.

En el diagrama siguiente se muestra la arquitectura antes y después de agregar el proxy de APIM.

Antes Cada autor de llamada se autentica directamente en GeoCatalog:

caller ──(Entra token)──► GeoCatalog

Una vez colocado APIM se sitúa entre los solicitantes y el GeoCatalog, gestionando la autenticación y el control de acceso.

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

Prerrequisitos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un recurso GeoCatalog existente.
Una instancia de Azure API Management.
Una identidad administrada asignada por el usuario a la instancia de APIM con una asignación de roles de GeoCatalog Reader a través del recurso GeoCatalog. Consulte Administración del acceso para obtener instrucciones de asignación de roles.

Asignación de la identidad administrada a APIM

Para que APIM pueda autenticarse en geocatalog, debe asociar la identidad administrada asignada por el usuario a la instancia de APIM.

Vaya a la instancia de API Management en Azure Portal.
Seleccione Identidad en la barra lateral izquierda.
Seleccione la pestaña Usuario asignado.
Seleccione Agregar y, a continuación, elija la identidad administrada asignada a un usuario que tenga el rol Lector de GeoCatalog en su GeoCatalog.
Seleccione Agregar para confirmar.

Creación de la API en APIM

Defina una nueva API en APIM que proxie las solicitudes al back-end de GeoCatalog.

En la instancia de APIM, seleccione API en la barra lateral izquierda.
Seleccione + Agregar API HTTP>.

Configure la API con los valores siguientes:

Configuración	Value
Nombre para mostrar	Un nombre descriptivo (por ejemplo, `GeoCatalog API`)
Dirección URL del servicio web	El punto de conexión de GeoCatalog (por ejemplo, `https://<name>.<id>.<region>.geocatalog.spatio.azure.com`).
Esquema de dirección URL	HTTPS
Sufijo de dirección URL de API	Dejar vacío (ruta de acceso raíz)
Suscripción necesaria	No, para el acceso anónimo; Sí, para el acceso basado en clave de suscripción

Selecciona Crear.

Definición de operaciones de API

Agregue las siguientes operaciones para que coincidan con la superficie de la API de GeoCatalog. Las operaciones comodín (/*) reenvían todas las solicitudes coincidentes al backend. Las operaciones de recopilación explícitas permiten aplicar directivas específicas de la colección más adelante para el control de acceso.

Nombre para mostrar	Método	Plantilla de dirección URL
OBTÉN	OBTÉN	`/*`
Obtener elementos de colección	OBTÉN	`/stac/collections/{collection_id}/items`
Obtener una sola colección	OBTÉN	`/stac/collections/{collection_id}`
Obtener subrecursos de recopilación	OBTÉN	`/stac/collections/{collection_id}/*`
POST	POST	`/*`

Para agregar cada operación:

Seleccione la API que ha creado.
Seleccione + Agregar operación.
Ingrese el Nombre para mostrar, Método y la Plantilla de URL de la tabla anterior.
Haga clic en Guardar.

Configure la política de nivel de API

La directiva de nivel de API controla la autenticación y la reescritura de direcciones URL para toda la API. Esta directiva adquiere un token de la identidad administrada asignada por el usuario y la asocia a cada solicitud reenviada al back-end de GeoCatalog.

Seleccione la API que ha creado y, a continuación, seleccione Todas las operaciones.
En la sección Procesamiento de entrada, seleccione el icono </> (editor de código).
Reemplace el contenido de la directiva por la siguiente directiva:

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

Reemplace los siguientes marcadores de posición:

Placeholder	Value
`<managed-identity-client-id>`	Identificador de cliente de la identidad gestionada asignada por el usuario a APIM
`<name>.<id>.<region>`	Componentes del punto de conexión de GeoCatalog
`<apim-name>`	Nombre de la instancia de APIM

En la tabla siguiente se describe cada elemento de directiva:

Elemento de política	propósito
`authentication-managed-identity`	Adquiere un token para la audiencia de `https://geocatalog.spatio.azure.com` mediante la identidad administrada especificada y lo asocia a la solicitud saliente.
`set-header` (eliminar `Accept-Encoding`)	Quita el `Accept-Encoding` encabezado de las solicitudes entrantes. Vea Por qué eliminar Accept-Encoding.
`find-and-replace`	Vuelve a escribir la dirección URL del back-end de GeoCatalog en los cuerpos de las respuestas a la dirección URL de la pasarela de APIM. Sin esta reescritura, los vínculos de STAC (`self`, `root`, `parent`, etc.) exponen la dirección URL de back-end a los autores de llamadas.

¿Por qué eliminar Accept-Encoding?

Los clientes como Python requests y httpx envían Accept-Encoding: gzip, deflate de forma predeterminada. Cuando el back-end recibe este encabezado, devuelve una respuesta comprimida. Las directivas de salida de APIM, como find-and-replace, operan en el cuerpo de la respuesta sin procesar y no pueden descomprimirla, por lo que no realizan ninguna acción. Quitar el encabezado obliga al back-end a devolver una respuesta sin comprimir que las directivas de salida pueden procesar.

Note

curl y wget no envíen Accept-Encoding de forma predeterminada. Esto significa que las directivas salientes parecen funcionar correctamente cuando se prueban con esas herramientas. La incoherencia solo se muestra con los clientes que solicitan compresión.

Aplicar el control de acceso a nivel de colección

De forma predeterminada, GeoCatalog expone todas sus colecciones a cualquier llamador autenticado. Para restringir qué colecciones son visibles a través de APIM, aplique directivas de nivel de operación que bloqueen la detección amplia de STAC y apliquen una lista de permitidos.

Definición de las colecciones permitidas

Cree un valor con nombre en APIM para almacenar la lista de identificadores de colección permitidos:

En la instancia de APIM, seleccione Valores con nombre en la barra lateral izquierda.
Seleccione +Agregar.
Establezca el nombre en allowed-collections.
Establezca el valor en una lista separada por comas de identificadores de colección permitidos (por ejemplo, sentinel-2-l2a,landsat-8-c2-l2).
Haga clic en Guardar.

Bloquear la página de aterrizaje y la lista de colecciones

Bloquee las rutas que revelan todas las colecciones del catálogo. Agregue las siguientes operaciones y adjunte una directiva que devuelva 404 inmediatamente:

Nombre para mostrar	Método	Plantilla de dirección URL
Bloquear raíz	OBTÉN	`/`
Bloquear colecciones	OBTÉN	`/stac/collections`

Aplique la siguiente directiva de nivel de operación a ambas operaciones:

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

Aplicación de recopilaciones permitidas en la búsqueda de STAC

El endpoint de STAC /stac/search acepta un parámetro collections, como cadena de consulta en GET o en el cuerpo JSON en POST. Sin límites de protección, un usuario puede buscar en todas las colecciones del catálogo. Las siguientes directivas validan que solo se solicitan colecciones del conjunto permitido.

Agregue dos operaciones:

Nombre para mostrar	Método	Plantilla de dirección URL
Búsqueda con GET	OBTÉN	`/stac/search`
Búsqueda con POST	POST	`/stac/search`

Directiva GET /stac/search

Esta directiva valida el parámetro de collections consulta. Cada valor separado por comas debe estar en el conjunto permitido. Las solicitudes sin un collections parámetro se rechazan con 403 Forbidden.

Aplique la siguiente directiva a la operación de búsqueda 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

Las expresiones de directiva de APIM se ejecutan en un entorno de C# restringido. Use condition='@{...}' (atributo entre comillas simples) para que las comillas dobles funcionen dentro de la expresión. Evite los parámetros de tipo genérico (por ejemplo, GetValueOrDefault<string>) y las expresiones lambda de LINQ: use en su lugar conversiones y foreach bucles explícitos.

Directiva POST /stac/search

Esta directiva analiza el cuerpo JSON y valida la collections matriz. Las solicitudes sin un collections parámetro se rechazan con 403 Forbidden.

Aplique la siguiente directiva a la operación de búsqueda 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>

Aplicación de recopilaciones permitidas en puntos de conexión de recopilación

Sin operaciones explícitas, solicitudes como GET /stac/collections/sentinel-2-l2a o GET /stac/collections/sentinel-2-l2a/items llevan al carácter comodín y llegan al back-end GET /* sin ninguna comprobación de nivel de colección. Aplique la directiva path-parameter que valida collection_id con {{allowed-collections}} las siguientes operaciones que creó en Definir operaciones de API:

Nombre para mostrar	Método	Plantilla de dirección URL
Obtener una sola colección	OBTÉN	`/stac/collections/{collection_id}`
Obtener subrecursos de recopilación	OBTÉN	`/stac/collections/{collection_id}/*`
Obtener elementos de colección	OBTÉN	`/stac/collections/{collection_id}/items`

Aplique la siguiente directiva a las tres operaciones:

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

Aplicación de recopilaciones permitidas en rutas de token de SAS

La API de SAS de GeoCatalog permite a los autores de llamadas generar tokens de almacenamiento y firmar HREF de activos. Sin restricciones, un llamante podría obtener tokens para cualquier colección. Las siguientes directivas garantizan que solo se pueda acceder a las colecciones permitidas.

Agregue las siguientes operaciones:

Nombre para mostrar	Método	Plantilla de dirección URL
Obtener token SAS	OBTÉN	`/sas/token/{collection_id}`
Bloqueo de signo de SAS	OBTÉN	`/sas/sign`

Aplique la directiva de bloqueo 404 (igual que el bloque raíz y colecciones) a la operación Bloquear signo de SAS . Los autores de llamadas deben usar /sas/token/{collection_id} para obtener tokens SAS de nivel de colección en su lugar.

Aplique la siguiente directiva a la operación de token de SAS 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[
                        "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>

Aplicación de colecciones permitidas en rutas de datos

Los puntos de conexión /data/mosaic/ proporcionan representación de iconos, recortes de rectángulo delimitador y registro de búsqueda. Se necesitan dos grupos de directivas:

Buscar en el registro - valide la collections matriz en el cuerpo JSON.
Todas las demás rutas de recopilación : valide el collectionId parámetro path.

Agregue las siguientes operaciones:

Nombre para mostrar	Método	Plantilla de dirección URL
Búsqueda en el registro POST	POST	`/data/mosaic/register`
Recopilación de datos GET	OBTÉN	`/data/mosaic/collections/{collectionId}/*`

Directiva POST/data/mosaic/register

Esta directiva valida la matriz collections en el cuerpo JSON frente al conjunto permitido. Las solicitudes sin un collections parámetro se rechazan.

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

Directiva GET /data/mosaic/collections/{collectionId}/*

Esta directiva valida el parámetro de ruta de acceso de collectionId frente al conjunto permitido. Aplique esta directiva a ambas operaciones de recopilación de datos 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>

Preguntas más frecuentes

¿Cómo actualizo la lista de recopilaciones permitidas?

Edite el valor nombrado allowed-collections en la instancia de APIM. No se necesitan cambios de directiva.

¿Qué ocurre si un llamante omite el parámetro collections?

La solicitud se rechaza con 403 Forbidden. Los autores de llamadas siempre deben especificar las colecciones que desean buscar.

Comentarios

¿Le resultó útil esta página?

Última actualización el 2026-05-27