Problemi noti e limitazioni dell'importazione dell'API

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Quando si importa un'API, è possibile che si verifichino alcune restrizioni o che sia necessario identificare e correggere i problemi prima di poter eseguire correttamente l'importazione. In questo articolo si apprenderà:

  • Comportamento di Gestione API durante l'importazione OpenAPI.
  • Limitazioni di importazione OpenAPI e funzionamento dell'esportazione OpenAPI.
  • Requisiti e limitazioni relativi alle importazioni WSDL e WADL.

Durante l'importazione OpenAPI, Gestione API

Durante l'importazione OpenAPI, Gestione API:

  • Verifica in modo specifico la presenza di parametri della stringa di query contrassegnati come richiesto.
  • Per impostazione predefinita, converte i parametri della stringa di query obbligatori in parametri di modello obbligatori.

Se si preferisce che i parametri di query obbligatori nella specifica vengano convertiti in parametri di query in Gestione API, disabilitare l'impostazione Includi parametri di query nei modelli di operazione durante la creazione dell'API nel portale. A tale scopo, è anche possibile usare le API REST API - Crea o aggiorna per impostare la proprietà translateRequiredQueryParameters dell'API su query.

Per le operazioni GET, HEAD e OPTIONS, Gestione API rimuove un parametro del corpo della richiesta, se definito nella specifica OpenAPI.

Limitazioni di importazione OpenAPI/Swagger

Se vengono restituiti errori durante l'importazione del documento OpenAPI, verificare che sia stato prima convalidato:

  • Usando la finestra di progettazione nel portale di Azure (Progettazione > Front End > Editor specifiche OpenAPI) o
  • Con uno strumento di terze parti, ad esempio Editor Swagger.

Generale

Requisiti del modello di URL

Requisito Descrizione
Nomi univoci per i parametri di query e percorso obbligatori In OpenAPI:
  • Un parametro deve essere univoco solo all'interno di una determinata posizione, ad esempio percorso, query, intestazione.
In Gestione API:
  • Le operazioni possono essere discriminate sia dai parametri di percorso che da quello di query.
  • OpenAPI non supporta questa discriminazione, per cui è necessario che i nomi dei parametri siano univoci all'interno dell'intero modello di URL.
Parametro URL definito Deve far parte del modello di URL.
URL del file di origine disponibile Applicato agli URL del relativo server.
Puntatori \$ref Non possono fare riferimento a file esterni.

Specifiche OpenAPI

Versioni supportate

Gestione API supporta solo:

  • OpenAPI versione 2.
  • OpenAPI versione 3.0.x (fino alla versione 3.0.3).
  • OpenAPI versione 3.1 (solo importazione)

Limitazioni delle dimensioni

Limite dimensioni Descrizione
Fino a 4 MB Quando una specifica OpenAPI viene importata inline in Gestione API.
Dimensioni delle richieste dell'API di Azure Resource Manager Quando un documento OpenAPI viene fornito tramite un URL a una posizione accessibile dal servizio Gestione API. Vedere Limiti della sottoscrizione di Azure.

Estensioni supportate

Le uniche estensioni supportate sono:

Estensione Descrizione
x-ms-paths
x-servers Un backport dell'oggetto OpenAPI 3 servers per OpenAPI 2.

Estensioni non supportate

Estensione Descrizione
Recursion Gestione API non supporta le definizioni definite in modo ricorsivo.
Ad esempio, gli schemi che fanno riferimento a se stessi.
Oggetto Server Non supportato a livello di operazione API.
Produces - Parola chiave Descrive i tipi MIME restituiti da un'API.
Non supportato.

Estensioni personalizzate

  • Vengono ignorate durante l'importazione.
  • Non vengono salvate o conservate per l'esportazione.

Definizioni non supportate

Le definizioni dello schema inline per le operazioni API non sono supportate. Le definizioni di schema:

  • Sono definite nell'ambito dell'API.
  • È possibile farvi riferimento negli ambiti di richiesta o risposta delle operazioni API.

Definizioni ignorate

Le definizioni di sicurezza vengono ignorate.

Restrizioni per le definizioni

Quando si importano parametri di query, è supportato solo il metodo di serializzazione della matrice predefinito (style: form, explode: true). Per altre informazioni sui parametri di query nelle specifiche OpenAPI, vedere la specifica di serializzazione.

I parametri definiti nei cookie non sono supportati. È comunque possibile usare i criteri per decodificare e convalidare il contenuto dei cookie.

OpenAPI versione 2

Il supporto di OpenAPI versione 2 è limitato solo al formato JSON.

I parametri di tipo "Modulo" non sono supportati. È comunque possibile usare i criteri per decodificare e convalidare i payload application/x-www-form-urlencoded e application/form-data.

OpenAPI versione 3.x

Gestione API supporta le versioni di specifica seguenti:

URL HTTPS

  • Se vengono specificati più servers, Gestione API userà il primo URL HTTPS trovato.
  • Se non sono presenti URL HTTPS, l'URL del server è vuoto.

Supportata

  • example

Non supportato

I campi seguenti sono inclusi in OpenAPI versione 3.0.x o OpenAPI versione 3.1.x, ma non sono supportati:

Oggetto Campo
OpenAPI externalDocs
info summary
Componenti
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Operazione
  • externalDocs
  • callbacks
  • security
  • servers
Parametro
  • allowEmptyValue
  • style
  • explode
  • allowReserved

Meccanismi di importazione, aggiornamento ed esportazione OpenAPI

Generale

Le definizioni API esportate da un servizio Gestione API sono:

  • Destinate principalmente ad applicazioni esterne che devono chiamare l'API ospitata nel servizio Gestione API.
  • Non devono essere importate nello stesso servizio Gestione API o in un servizio diverso.

Per la gestione della configurazione delle definizioni API in diversi servizi/ambienti, vedere la documentazione relativa all'uso del servizio Gestione API con Git.

Aggiungere una nuova API tramite l'importazione OpenAPI

Per ogni operazione trovata nel documento OpenAPI, viene creata una nuova operazione con:

  • Nome della risorsa di Azure impostato su operationId.

    • Il valore operationId è normalizzato.
    • Se operationId non è specificato (non presente, null o vuoto), il valore del nome della risorsa di Azure viene generato combinando il metodo HTTP e il modello di percorso.
      • Ad esempio, get-foo.

  • Nome visualizzato impostato su summary.

    • Valore summary:
      • Importato così come è.
      • La lunghezza è limitata a 300 caratteri.
    • Se summary non è specificato (non presente, null o vuoto), il valore del nome visualizzato verrà impostato su operationId.

Regole di normalizzazione per operationId

  • Consente di convertire la stringa in caratteri minuscoli.
  • Sostituire ogni sequenza di caratteri non alfanumerici con un singolo trattino.
    • Ad esempio, GET-/foo/{bar}?buzz={quix} viene trasformato in get-foo-bar-buzz-quix-.
  • Tagliare i trattini su entrambi i lati.
    • Ad esempio get-foo-bar-buzz-quix- diventa get-foo-bar-buzz-quix
  • Troncare per contenere 76 caratteri, quattro caratteri in meno del limite massimo per un nome di risorsa.
  • Usare i quattro caratteri rimanenti per un suffisso di deduplicazione, se necessario, sotto forma di -1, -2, ..., -999.

Aggiornare un'API esistente tramite l'importazione OpenAPI

Durante l'importazione, l'operazione API esistente:

  • Viene modificata in base all'API descritta nel documento OpenAPI.
  • Corrisponde a un'operazione nel documento OpenAPI confrontando il relativo valore operationId con il nome della risorsa di Azure dell'operazione esistente.
    • Se viene trovata una corrispondenza, le proprietà dell'operazione esistente vengono aggiornate "in posizione".
    • Se non viene trovata una corrispondenza:
      • Viene creata una nuova operazione combinando il metodo HTTP e il modello di percorso, ad esempio get-foo.
      • Per ogni nuova operazione, l'importazione tenterà di copiare i criteri da un'operazione esistente con lo stesso metodo HTTP e lo stesso modello di percorso.

Tutte le operazioni non corrispondenti esistenti vengono eliminate.

Per rendere l'importazione più prevedibile, seguire queste linee guida:

  • Specificare la proprietà operationId per ogni operazione.
  • Evitare di modificare operationId dopo l'importazione iniziale.
  • Non modificare mai operationId e il metodo HTTP o il modello di percorso contemporaneamente.

Regole di normalizzazione per operationId

  • Consente di convertire la stringa in caratteri minuscoli.
  • Sostituire ogni sequenza di caratteri non alfanumerici con un singolo trattino.
    • Ad esempio, GET-/foo/{bar}?buzz={quix} viene trasformato in get-foo-bar-buzz-quix-.
  • Tagliare i trattini su entrambi i lati.
    • Ad esempio get-foo-bar-buzz-quix- diventa get-foo-bar-buzz-quix
  • Troncare per contenere 76 caratteri, quattro caratteri in meno del limite massimo per un nome di risorsa.
  • Usare i quattro caratteri rimanenti per un suffisso di deduplicazione, se necessario, sotto forma di -1, -2, ..., -999.

Esportare l'API come OpenAPI

Per ogni operazione:

  • Il nome della risorsa di Azure viene esportato come operationId.
  • Il nome visualizzato viene esportato come summary.

La normalizzazione di operationId viene eseguita al momento dell'importazione, non dell'esportazione.

WSDL

È possibile creare le API SOAP pass-through e SOAP-to-REST con file WSDL.

Associazioni SOAP

  • Solo le associazioni SOAP con stile di codifica "document" e "literal" sono supportate.
  • Nessun supporto per lo stile "rpc” o la codifica SOAP.

Importazioni e inclusioni

  • Le direttive wsdl:import, xsd:import e xsd:include non sono supportate. Unire invece le dipendenze in un unico documento.

  • Per fare in modo che uno strumento open source risolva e unisca le dipendenze wsdl:import, xsd:importe xsd:include in un file WSDL, vedere questo repository GitHub.

Specifiche WS-*

I file WSDL che incorporano le specifiche WS-* non sono supportati.

Messaggi con più parti

Questo tipo di messaggio non è supportato.

WCF wsHttpBinding

  • I servizi SOAP creati con Windows Communication Foundation devono usare basicHttpBinding.
  • wsHttpBinding non è supportata.

MTOM

  • I servizi che usano MTOMpossono funzionare.
  • Al momento il supporto ufficiale non è previsto.

Ricorsione

  • I tipi definiti in modo ricorsivo non sono supportati da Gestione API.
  • Ad esempio, fare riferimento a una matrice di se stessi.

Più spazi dei nomi

Nonostante più spazi dei nomi possano essere usati in uno schema, solo lo spazio dei nomi di destinazione può essere usato per definire le parti del messaggio. Questi spazi dei nomi vengono usati per definire altri elementi di input o output.

Gli spazi dei nomi diversi dalla destinazione non vengono mantenuti durante l'esportazione. Sebbene sia possibile importare un documento WSDL che definisce parti di messaggio con altri spazi dei nomi, tutte le parti del messaggio avranno lo spazio dei nomi di destinazione WSDL nell'esportazione.

Più endpoint

I file WSDL possono definire più servizi ed endpoint (porte) da uno o più elementi wsdl:service e wsdl:port. Tuttavia, il gateway di Gestione API è in grado di importare e inviare a un server proxy le richieste eseguite solo a un singolo servizio e endpoint. Se nel file WSDL sono definiti più servizi o endpoint, identificare il nome e l'endpoint del servizio di destinazione durante l'importazione dell'API usando la proprietà wsdlSelector.

Suggerimento

Se si desidera bilanciare il carico delle richieste tra più servizi ed endpoint, è consigliabile configurare un pool di back-end con bilanciamento del carico.

Matrici

La trasformazione da SOAP a REST supporta solo matrici di cui è stato eseguito il wrapping illustrate nell'esempio seguente:

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

Attualmente non sono noti problemi di importazione del formato WADL.