Pubblicare le API di Microsoft Azure Data Manager per l'energia in un gateway API protetto
Azure Gestione API funge da intermediario cruciale tra le applicazioni client e le API back-end. Semplifica l'accesso dei client ai servizi nascondendo i dettagli tecnici e assegnando alle organizzazioni il controllo sulla sicurezza delle API.
Pubblicando le API di Azure Data Manager per l'energia tramite Azure Gestione API, è possibile usare la funzionalità Azure Data Manager for Energy collegamento privato per il traffico privato e rimuovere completamente l'accesso pubblico diretto all'istanza.
Questo articolo descrive come configurare azure Gestione API per la protezione delle API di Azure Data Manager per l'energia.
Prerequisiti
Per completare questa procedura dettagliata sono necessari i componenti, gli strumenti e le informazioni seguenti:
Una rete virtuale con due subnet disponibili, una per l'endpoint privato di Azure Data Manager per l'energia e l'altra per Azure Gestione API l'inserimento della rete virtuale.
Azure Data Manager for Energy configurato con collegamento privato distribuito nella subnet.
Azure Gestione API effettuato il provisioning e la distribuzione nella rete virtuale usando l'inserimento della rete virtuale. Selezionare Modalità esterna oppure vedere la sezione Altre opzioni per La modalità interna .
Un editor di codice, ad esempio Visual Studio Code , per modificare le specifiche di Azure Data Manager per Energy OpenAPI per ognuna delle API da pubblicare.
Scaricare le specifiche di Azure Data Manager per Energy OpenAPI dal repository GitHub adme-samples . Passare alla directory rest-apis e selezionare la versione appropriata per l'applicazione.
Dalla registrazione dell'app per l'app Azure Data Manager for Energy usata in fase di provisioning prendere nota dell'ID tenant e dell'ID client:
Preparare l'istanza di Gestione API
Usare la procedura seguente per apportare modifiche di configurazione all'istanza di Azure Gestione API:
Nel riquadro Tutte le risorse scegliere l'istanza di Azure Gestione API usata per questa procedura dettagliata.
Passare alla pagina Impostazioni prodotti scegliendola dal raggruppamento delle impostazioni API:
Nella pagina Prodotti selezionare il pulsante Aggiungi per creare un nuovo prodotto. Azure Gestione API Products consente di creare un raggruppamento di API ad accoppiamento libero che possono essere regolate e gestite insieme. Viene creato un prodotto per le API Di Azure Data Manager per l'energia.
Nella pagina Aggiungi prodotto immettere i valori descritti nella tabella seguente per creare il prodotto.
Impostazione Valore Nome visualizzato "Azure Data Manager for Energy Product" ID "adme-product" Descrizione Immettere una descrizione che indica agli sviluppatori le API da raggruppare Pubblicazione completata Selezionare questa casella per pubblicare il prodotto creato Richiede la sottoscrizione Selezionare questa casella per fornire l'autorizzazione di base per le API Richiede approvazione Facoltativamente, selezionare se si vuole che un amministratore rivedi e accetti o rifiuti i tentativi di sottoscrizione a questo prodotto. Se non è selezionata, i tentativi di sottoscrizione vengono approvati automaticamente. Limite per il numero di sottoscrizioni Consente di limitare il numero di più sottoscrizioni simultanee. Note legali Facoltativamente, definire le condizioni per l'utilizzo per il prodotto che i sottoscrittori devono accettare per utilizzare il prodotto. API È possibile ignorare questa funzionalità. Le API vengono associate più avanti in questo articolo Fare clic su Crea per creare il nuovo prodotto.
Al termine della creazione del prodotto, il portale torna alla pagina Prodotti. Selezionare il prodotto appena creato Azure Data Manager per Il prodotto energia per passare alla pagina Risorsa prodotto. Selezionare la voce di menu Impostazioni criteri dal menu delle impostazioni.
Nel riquadro Elaborazione in ingresso selezionare l'icona </> , che consente di modificare i criteri per il prodotto. Si aggiungono tre set di criteri per migliorare la sicurezza della soluzione:
- Convalidare il token ID Entra per assicurarsi che le richieste non autenticate vengano intercettati nel gateway API
- Quota e limite di frequenza per controllare la frequenza di richieste e richieste totali/dati trasferiti
- Impostare Intestazione per rimuovere le intestazioni restituite dalle API back-end, che potrebbero rivelare dettagli sensibili a potenziali attori malintenzionati
Aggiungere i criteri validate-azure-ad-token seguenti alla configurazione all'interno dei tag in ingresso e sotto il tag di base. Assicurarsi di aggiornare il modello con i dettagli dell'app Microsoft Entra ID annotati nei prerequisiti.
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>Sotto i criteri validate-azure-ad-token aggiungere i criteri di quota e limite di frequenza seguenti. Aggiornare i valori di configurazione dei criteri in base alle esigenze dei consumer.
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />Nella sezione in uscita dell'editor dei criteri e nel tag di base aggiungere i criteri set-header seguenti.
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />Seleziona Salva per applicare le modifiche.
Tornare alla risorsa Gestione API nella portale di Azure. Selezionare la voce di menu Back-end e selezionare il pulsante + Aggiungi .
In Modalità back-end immettere i valori descritti nella tabella seguente per creare il back-end.
Impostazione valore Nome "adme-backend" Descrizione Immettere una descrizione che indica agli sviluppatori che questo back-end è correlato ad Azure Data Manager per le API Energy Type URL personalizzato Runtime URL Immettere il _ex dell'URI di Azure Data Manager per l'URI dell'energia. https://INSERT_ADME_NAME.energy.azure.com/Convalidare la catena di certificati Selezionato Convalidare il nome del certificato Selezionato 
Selezionare Crea per creare il back-end. Questo back-end appena creato verrà usato nella sezione successiva quando si pubblicano le API.
Importare Le API di Azure Data Manager per l'energia
Usare la procedura seguente per importare, configurare e pubblicare le API di Azure Data Manager per l'energia nel gateway Gestione API di Azure:
Tornare all'istanza di Azure Gestione API usata nell'ultima sezione.
Selezionare la voce di menu API dal menu e quindi selezionare il pulsante + Aggiungi API .
Selezionare OpenAPI sotto l'intestazione Crea dalla definizione.
Nella finestra modale Crea dalla specifica OpenAPI selezionare l'interruttore Completo .
Individuare le specifiche OpenAPI scaricate come parte dei prerequisiti e aprire la specifica dello schema usando l'editor di codice preferito. Cercare la parola "server" e annotare l'URL del server nel file , ad esempio /api/schema-service/v1/.
Selezionare Seleziona un file e selezionare la specifica dell'API schema . Al termine del caricamento, la finestra modale carica alcuni valori dalla specifica.
Per gli altri campi, immettere i valori descritti nella tabella seguente:
Impostazione Valore Includere i parametri di query necessari nei modelli di operazione Selezionato Nome visualizzato Immettere un nome visualizzato appropriato per gli sviluppatori di app, ad esempio Azure Data Manager per il servizio Energy Schema Service Nome Gestione API suggerisce un nome kebab-cased. Facoltativamente, il nome può essere modificato, ma deve essere univoco per l'istanza Descrizione La specifica OpenAPI può definire una descrizione, se la descrizione viene popolata automaticamente. Facoltativamente, aggiornare la descrizione in base al caso d'uso. Schema URL Selezionare "Entrambi" Suffisso dell'URL dell'API Immettere un suffisso per tutte le API di Azure Data Manager per l'energia (ad esempio adme). Immettere quindi l'URL del server nel passaggio 5. Il valore finale dovrebbe essere simile a /adme/api/schema-service/v1/. Un suffisso consente di essere conformi ai client esistenti e ai kit di sviluppo software che normalmente si connettono direttamente alle API di Azure Data Manager per l'energia Tag Facoltativamente, immettere i tag Prodotti Selezionare il prodotto "Azure Data Manager for Energy" creato nella sezione precedente Importante
Convalidare il suffisso DELL'URL dell'API, questa è una causa comune di errori durante la pubblicazione delle API di Azure Data Manager per l'energia
Selezionare Crea per creare la facciata dell'API.
Selezionare la facciata dell'API schema appena creata dall'elenco delle API e selezionare Tutte le operazioni nell'elenco delle operazioni. Nel riquadro Elaborazione in ingresso selezionare l'icona </>per modificare il documento dei criteri.
Per configurare l'API, aggiungere due set di criteri:
- Impostare il servizio back-end per instradare le richieste all'istanza di Azure Data Manager per l'energia
- Riscrivere l'URI per rimuovere il prefisso adme e compilare la richiesta all'API back-end. Questa istruzione dei criteri usa espressioni di criteri per aggiungere dinamicamente il valore del modello URL dell'operazione corrente all'URL del server.
Annotare l'URL del server dal passaggio 5. Sotto il tag di base , nella sezione in ingresso , inserire le due istruzioni di criteri seguenti.
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />Seleziona Salva per applicare le modifiche.
Testare l'API selezionando l'operazione GET Version info nell'elenco delle operazioni. Selezionare quindi la scheda Test per passare alla console di test di Azure Gestione API.
Immettere i valori descritti nella tabella seguente. Generare un token di autenticazione per Azure Data Manager per l'energia. Selezionare Invia per testare l'API.
Impostazione Valore data-partition-id ID partizione dati per l'istanza di Azure Data Manager per l'energia Prodotto Selezionare il prodotto Azure Data Manager for Energy creato in precedenza Autorizzazione "Bearer" e il token di autenticazione generati 
Se l'API è configurata correttamente, verrà visualizzata una risposta HTTP 200 - OK simile allo screenshot. In caso contrario, controllare la sezione Risoluzione dei problemi.
Ripetere i passaggi precedenti per ogni AZURE Data Manager per l'API Energy e la specifica associata.
Risoluzione dei problemi
Durante il test delle API tramite Azure Gestione API, se si verificano errori che in genere puntano a problemi di configurazione. In base all'errore, esaminare i passaggi di risoluzione potenziali.
| Codice | Messaggio d'errore | Dettagli |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
Verificare di disporre di un'intestazione di autenticazione valida per il tenant e l'app client Microsoft Entra ID per l'istanza di Azure Data Manager per l'energia. |
HTTP 401 Unauthorized |
Azure AD JWT not present |
Verificare che l'intestazione di autenticazione venga aggiunta alla richiesta di test. |
HTTP 404 Not Found |
Questo errore indica in genere che la richiesta all'API back-end viene inviata all'URL errato. Tracciare la richiesta API in Gestione API per comprendere l'URL generato per la richiesta back-end e assicurarsi che sia valido. In caso contrario, controllare il criterio url-rewrite o il back-end. | |
HTTP 500 Internal Server Error |
Internal server error |
Questo errore riflette in genere un problema che effettua richieste all'API back-end. In genere, in questo scenario, il problema è correlato ai servizi dei nomi di dominio (DNS). Verificare che nella rete virtuale sia configurata una zona DNS privata o che la risoluzione DNS personalizzata abbia i server d'inoltro appropriati. Tracciare la richiesta API in Gestione API per comprendere quale richiesta back-end è stata effettuata e quali errori Gestione API viene segnalato quando si tenta di effettuare la richiesta. |
Altre considerazioni
Gestione API modalità di rete virtuale interna
La modalità interna isola completamente il Gestione API di Azure invece di esporre gli endpoint tramite indirizzo IP pubblico. In questa configurazione, le organizzazioni possono garantire che tutti i data manager di Azure per l'energia siano interni. Poiché Azure Data Manager per l'energia è una soluzione di collaborazione per lavorare con partner e clienti, questo scenario potrebbe non essere utile così come è.
Gateway app con web application firewall
Invece di usare solo la modalità di rete virtuale interna, molte organizzazioni scelgono di applicare un meccanismo di proxy inverso protetto per esporre l'istanza di Azure Gestione API modalità interna a partner e clienti esterni. L'istanza della modalità interna rimane completamente isolata con un ingresso strettamente controllato che deve passare attraverso il proxy.
app Azure Gateway è un servizio comune da usare come proxy inverso. app Azure Gateway ha anche una funzionalità web application firewall (WAF), che rileva attivamente potenziali attacchi contro le vulnerabilità nelle applicazioni e nelle API.
Configurazione di Azure Gestione API con un dominio personalizzato
Un'altra caratteristica comune di questa architettura consiste nell'applicare un dominio personalizzato alle API. Anche se Azure Data Manager for Energy non supporta questa funzionalità, è invece possibile configurare un dominio personalizzato in Azure Gestione API.
Un certificato per il dominio è un prerequisito. Tuttavia, Azure Gestione API supporta la creazione di certificati gestiti gratuiti per il dominio personalizzato.