Integrare Azure API Management con l'API Fabric per GraphQL

L'integrazione di Gestione API di Azure con l'API di Microsoft Fabric per GraphQL migliora significativamente le funzionalità dell'API offrendo funzionalità affidabili di scalabilità e sicurezza. Gestione API agisce come un gateway di livello aziendale che aggiunge funzionalità avanzate, tra cui la gestione delle identità, la limitazione del ritmo, la memorizzazione delle risposte nella cache, la protezione dalle minacce e il monitoraggio centralizzato, il tutto senza modificare la configurazione della tua API Fabric.

Instradando le richieste GraphQL tramite Gestione API, è possibile ridimensionare per gestire un maggiore traffico, implementare criteri di sicurezza sofisticati e ottenere visibilità sui modelli di utilizzo delle API nell'organizzazione.

Questo articolo guida l'integrazione di APIM con Fabric API per GraphQL, la configurazione dell'autenticazione dell'identità gestita e l'implementazione di politiche di caching e limitazione del rate.

Chi usa Gestione API di Azure con GraphQL

L'integrazione della Gestione delle API è utile per:

Architetti aziendali che espongono i dati di Fabric tramite un gateway API centralizzato e regolamentato per l'accesso a livello di organizzazione
Amministratori dell'infrastruttura che implementano criteri di limitazione della frequenza, memorizzazione nella cache e sicurezza per proteggere la capacità e i dati dell'infrastruttura
Team di sicurezza IT che richiedono l'autenticazione avanzata, l'autorizzazione e la protezione dalle minacce per l'accesso ai dati di Fabric
Team della piattaforma che gestiscono e governano più API GraphQL Fabric tra reparti e unità aziendali

Usa l'integrazione di API Management quando sono necessarie funzionalità di gestione API di livello aziendale, come la limitazione della velocità, il caching, i criteri di sicurezza e la governance centralizzata per le API GraphQL di Fabric.

Prerequisiti

Prima di iniziare, assicurarsi di disporre di:

API Fabric per GraphQL già creata. In caso contrario, vedere Creare un'API per GraphQL o usare Iniziare con il database SQL di esempio nell'API per il portale GraphQL
Un'istanza di Gestione API. Per istruzioni sull'installazione, vedere Creare un'istanza di Gestione API
Autorizzazioni per creare identità gestite e configurare politiche di gestione delle API

Aggiungere un'API GraphQL di Fabric a Gestione API di Azure

Il primo passaggio per l'integrazione di Gestione delle API con Fabric consiste nell'importare l'API GraphQL in Gestione delle API di Azure. Questo processo crea un proxy che instrada le richieste tramite APIM (Gestione API) mantenendo la connessione alle origini dati di Fabric. Importando l'API, si stabilisce la base per l'aggiunta di funzionalità aziendali come criteri di autenticazione, memorizzazione nella cache e limitazione della frequenza.

Il processo di importazione richiede due informazioni dall'API GraphQL di Fabric: l'URL dell'endpoint (in cui Gestione API invia le richieste) e il file di schema (che definisce la struttura API e le operazioni disponibili).

Esportare i dettagli dell'API GraphQL

Prima di tutto, raccogliere le informazioni necessarie dall'API GraphQL di Fabric:

Aprire l'API GraphQL nel portale di Fabric
Nella barra multifunzione selezionare Copia endpoint per ottenere l'URL dell'API
Selezionare Esporta schema per scaricare il file di schema GraphQL nel dispositivo locale

Importare l'API in APIM

Con l'URL dell'endpoint e il file di schema pronti, è ora possibile registrare l'API GraphQL in Gestione API. In questo modo viene creata una definizione API usata da Gestione API per convalidare le richieste, generare la documentazione e applicare i criteri. Lo schema caricato definisce le query e le mutazioni che i client possono eseguire.

Passare all'istanza di Gestione API nel portale di Azure
Selezionare API>+ Aggiungi API
Selezionare l'icona GraphQL
Nella schermata Crea da schema GraphQL specificare:
- Nome visualizzato: nome descrittivo per l'API
- Nome: identificatore DELL'API
- Endpoint dell'API GraphQL: l'URL dell'endpoint copiato da Fabric
Selezionare Carica schema e scegliere il file di schema scaricato

Configurare l'autenticazione dell'identità gestita

Ora che l'API GraphQL è registrata in Gestione API, è necessario configurare la modalità di autenticazione di Gestione API con Fabric. Le identità gestite offrono un metodo di autenticazione sicuro e senza password che elimina la necessità di memorizzare le credenziali nella configurazione di Gestione API. Azure gestisce automaticamente il ciclo di vita dell'identità e gestisce l'acquisizione dei token, rendendo questo approccio più sicuro e più semplice da gestire rispetto ai metodi di autenticazione tradizionali.

La configurazione dell'autenticazione prevede tre passaggi principali: la creazione dell'identità gestita in Azure, la concessione delle autorizzazioni per accedere all'area di lavoro e alle origini dati dell'infrastruttura e la configurazione di Gestione API per l'uso di questa identità durante l'esecuzione di richieste a Fabric.

Creare e assegnare un'identità gestita

Per prima cosa, crea l'identità gestita che il Gestione API utilizza per l'autenticazione:

Creare un'identità gestita assegnata dall'utente nel portale di Azure.
Prendere nota dell'ID client dell'identità gestita. È necessario l'ID client per la configurazione dei criteri.

Concedere le autorizzazioni per l'identità gestita in Fabric

Dopo aver creato l'identità gestita, è necessario concedergli le autorizzazioni per accedere alle risorse di Fabric. L'identità gestita deve accedere sia all'elemento dell'API GraphQL che a tutte le origini dati a cui si connette ,ad esempio lakehouse o warehouse. L'aggiunta dell'identità come membro dell'area di lavoro è l'approccio più semplice perché concede l'accesso a tutti gli elementi dell'area di lavoro contemporaneamente.

Aprire l'area di lavoro Fabric contenente l'API GraphQL
Selezionare Gestisci accesso
Aggiungere l'identità gestita, ad esempio apim-id, con almeno il ruolo Collaboratore

Suggerimento

Per un controllo più granulare, è possibile concedere le autorizzazioni direttamente a singoli elementi dell'infrastruttura (l'API e le relative origini dati) anziché l'accesso a livello di area di lavoro. Il controllo granulare è particolarmente importante se l'API usa l'autenticazione Single Sign-On (SSO). Per altre informazioni, vedere Riepilogo delle autorizzazioni e dell'autenticazione.

Configurare APIM per utilizzare l'identità gestita

Con le autorizzazioni concesse in Fabric, è necessario specificare ad APIM quale identità gestita utilizzare. Questa associazione permette ad APIM di autenticarsi come quell'identità quando si effettuano richieste alla tua API GraphQL di Fabric.

Nel portale di Azure, passa alla tua istanza di Gestione API
Passare a Sicurezza>Identità gestite
Aggiungere l'identità gestita assegnata dall'utente creata in precedenza

Aggiungere criteri di autenticazione

Il passaggio di autenticazione finale consiste nell'aggiungere un criterio APIM che ottiene un token di accesso utilizzando l'identità gestita e lo include nelle richieste a Fabric. Questa politica viene eseguita a ogni richiesta, gestendo automaticamente l'acquisizione e il rinnovo del token. Il criterio usa l'elemento authentication-managed-identity per ottenere un token per la risorsa Fabric API, quindi lo aggiunge all'intestazione Authorization.

Nell'API GraphQL in APIM, selezionare la scheda Criteri API
Modificare i criteri di elaborazione in ingresso

Aggiungere il codice XML seguente in <inbound><base/>:

<authentication-managed-identity 
    resource="https://analysis.windows.net/powerbi/api" 
    client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
    output-token-variable-name="token-variable" 
    ignore-error="false" />
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
</set-header>

Sostituire YOUR-MANAGED-IDENTITY-CLIENT-ID con l'ID client dell'identità gestita
Salvare la politica

Testare la connessione

Prima di procedere per aggiungere la memorizzazione nella cache e la limitazione della frequenza, verificare che l'installazione dell'autenticazione funzioni correttamente. Il test garantisce ora che eventuali problemi riscontrati in un secondo momento non siano correlati alla configurazione dell'autenticazione.

In APIM, navigare alla tua API GraphQL
Passare alla scheda Test
Eseguire una query di esempio o una mutazione per confermare il funzionamento della connessione

Configurare la memorizzazione nella cache delle risposte

La memorizzazione nella cache delle risposte riduce significativamente la latenza per i chiamanti API e riduce il carico back-end nelle origini dati di Fabric. APIM supporta la memorizzazione nella cache predefinita o le istanze Redis esterne. Per le API GraphQL, la memorizzazione nella cache usa il corpo della richiesta (la query GraphQL) come chiave della cache, assicurando che le query identiche restituiscono risposte memorizzate nella cache.

Vantaggi della memorizzazione nella cache delle risposte GraphQL:

Latenza ridotta: le risposte memorizzate nella cache restituiscono immediatamente senza eseguire query su Fabric
Minore consumo di capacità: meno richieste a Fabric riducono l'utilizzo di CU (unità di capacità)
Maggiore scalabilità: gestire più utenti simultanei senza aumentare il carico back-end

Aggiungere politica di memorizzazione nella cache

Per implementare la memorizzazione nella cache, modificare i criteri di autenticazione esistenti per aggiungere la logica di ricerca e archiviazione della cache. La politica controlla le risposte memorizzate nella cache prima di inoltrare le richieste a Fabric e memorizza le risposte riuscite per un uso futuro. Questo esempio completo di criteri mostra come interagiscono l'autenticazione e la memorizzazione nella cache:

<policies>
    <inbound>
        <base />
        <!-- Authenticate with managed identity -->
        <authentication-managed-identity 
            resource="https://analysis.windows.net/powerbi/api" 
            client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
            output-token-variable-name="token-variable" 
            ignore-error="false" />
        <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
        </set-header>
        <!-- Check if response is cached -->
        <cache-lookup-value 
            key="@(context.Request.Body.As<String>(preserveContent: true))" 
            variable-name="cachedResponse" 
            default-value="not_exists" />
    </inbound>
    <backend>
        <!-- Only forward request if not cached -->
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists")">
                <forward-request />
            </when>
        </choose>
    </backend>
    <outbound>
        <base />
        <choose>
            <!-- Return cached response if it exists -->
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") != "not_exists")">
                <set-body>@(context.Variables.GetValueOrDefault<string>("cachedResponse"))</set-body>
            </when>
            <!-- Cache successful responses for 60 seconds -->
            <when condition="@((context.Response.StatusCode == 200) && (context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists"))">
                <cache-store-value 
                    key="@(context.Request.Body.As<String>(preserveContent: true))" 
                    value="@(context.Response.Body.As<string>(preserveContent: true))" 
                    duration="60" />
            </when>
        </choose>
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Funzionamento di questo criterio:

In ingresso: esegue l'autenticazione con l'identità gestita e verifica se la risposta viene memorizzata nella cache in base alla query GraphQL
Back-end: ignora l'inoltro della richiesta a Fabric se esiste una risposta memorizzata nella cache
In uscita: restituisce risposte memorizzate nella cache o memorizza nella cache nuove risposte riuscite per 60 secondi

Verificare che la memorizzazione nella cache funzioni

Per confermare che le richieste vengono memorizzate nella cache:

In APIM, eseguire la stessa query GraphQL due volte
Tracciare la chiamata API per visualizzare i riscontri nella cache

Ottimizzare la durata della cache

Nell'esempio viene utilizzata una durata della cache di 60 secondi. Modificare la durata in base ai requisiti di aggiornamento dei dati:

Aggiornamenti ad alta frequenza: usare durate più brevi (10-30 secondi) per i dati che cambiano di frequente
Dati statici o di riferimento: usare durate più lunghe (5-60 minuti) per i dati che cambiano raramente
Requisiti in tempo reale: non memorizzare nella cache le query che devono restituire sempre i dati più recenti

Per scenari di caching avanzati, tra cui l'invalidazione della cache e la configurazione esterna di Redis, vedere Criteri di caching di APIM.

Limitazione della velocità

È possibile limitare il numero di chiamate API che un client può effettuare in un periodo di tempo specifico. Ecco una regola di limitazione della frequenza di esempio che puoi aggiungere sotto <inbound><base/> per applicare non più di due chiamate ogni 60 secondi per un determinato utente.

<rate-limit-by-key 
    calls="2" 
    renewal-period="60" 
    counter-key="@(context.Request.Headers.GetValueOrDefault("Authorization"))" 
    increment-condition="@(context.Response.StatusCode == 200)" 
    remaining-calls-variable-name="remainingCallsPerUser" />

Dopo l'invio di più di due chiamate API in un minuto, viene visualizzato un messaggio di errore:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in 58 seconds."
}

Per ulteriori informazioni su come configurare i criteri di limitazione della velocità in Gestione delle API, vedere la documentazione.

Procedure consigliate

Quando si integra APIM con Fabric API per GraphQL, seguire queste raccomandazioni:

Security

Usare le identità gestite: preferisce le identità gestite rispetto alle chiavi API o alle stringhe di connessione per l'autenticazione
Implementare privilegi minimi: concedere solo le autorizzazioni minime necessarie per l'identità gestita
Abilitare solo HTTPS: Configurare APIM per rifiutare le richieste HTTP e forzare l'uso di HTTPS
Convalidare gli input: usare i criteri di APIM per convalidare le query GraphQL prima di inoltrarle a Fabric

Performance

Memorizzare nella cache i dati a cui si accede di frequente: identificare le query comuni e impostare le durate della cache appropriate
Monitorare il tasso di successo della cache: utilizzare le analisi di APIM per tenere traccia dell'efficacia della cache
Ottimizzare i limiti di velocità: bilanciare l'esperienza utente con la protezione della capacità
Usare la distribuzione regionale: Distribuire APIM nella stessa area della capacità del Fabric

Monitoraggio e governance

Abilitare la diagnostica: configurare il logging diagnostico di API Management per tenere traccia dell'utilizzo dell'API
Configurare gli avvisi: creare avvisi per le violazioni e gli errori del limite di frequenza
Versiona le tue API: usa la versione di APIM per gestire eventuali modifiche di rilievo
Documentare le API: usare il portale per sviluppatori di API Management per fornire la documentazione delle API

Ottimizzazione dei costi

Limiti di frequenza adeguati: Impostare limiti allineati al livello di capacità
Monitorare il consumo di capacità: Tenere traccia sia dell'utilizzo della capacità di Gestione API che della capacità di Fabric
Usare la memorizzazione nella cache in modo strategico: bilanciare i requisiti di aggiornamento con il risparmio di capacità
Esaminare i modelli di utilizzo: analizzare regolarmente le query che usano la maggior parte delle risorse

Riassunto

L'integrazione dell'API di Microsoft Fabric per GraphQL con Azure Gestione API unisce le potenti funzionalità di dati di Fabric con le caratteristiche avanzate di gateway API a livello aziendale di Azure Gestione API. Questa combinazione fornisce:

Sicurezza avanzata: autenticazione dell'identità gestita, protezione dalle minacce e controllo degli accessi basato su criteri
Scalabilità migliorata: memorizzazione nella cache delle risposte, limitazione della frequenza e distribuzione del carico tra più back-end
Prestazioni migliori: riduzione della latenza tramite la memorizzazione nella cache e il routing delle richieste ottimizzato
Governance centralizzata: monitoraggio unificato, controllo delle versioni e gestione in più API
Controllo dei costi: limitazione della velocità e memorizzazione nella cache per ridurre il consumo di capacità dell'infrastruttura

Seguendo i passaggi di configurazione e le procedure consigliate in questo articolo, è possibile creare un livello API affidabile, sicuro e scalabile che supporti i carichi di lavoro di produzione nell'organizzazione.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-01-20