Proprietà API

Modifica online

Le proprietà vengono utilizzate dal gateway per controllare il comportamento di determinate politiche. Di solito, si forniscono le proprietà, ma la politica può fornire anche le impostazioni delle proprietà.

In IBM® API Connectè possibile creare proprietà API costituite da valori specifici del catalogo per eliminare la necessità di modifiche del codice sorgente. Puoi quindi fare riferimento alle proprietà altrove nella tua definizione API.

Proprietà API predefinite

Le proprietà API prefornite per le varie politiche vengono mostrate nelle tabelle.

Un elenco di proprietà API correlate al richiamo che controllano il comportamento della politica di richiamo.

Tabella 1. Proprietà che controllano la politica di invocazione
Proprietà	Obbligatorio	Descrizione	Tipo di dati
x-ibm-gateway-decode-request-params	N	Se impostato su un valore di `true`, tutti i parametri di richiesta a cui fa riferimento una definizione di variabile su un invoke target-url vengono decodificati con l' URL. Il comportamento predefinito è quello di non decodificare alcun parametro, inviandoli così all' URL e di destinazione senza alterazioni.	Booleano
x-ibm-gateway-invoke-suppress-clientid	N	Quando impostato con un valore di `true`, o non specificato, l'intestazione X- IBM -Client-Id HTTP (se specificata nella richiesta API) non viene inviata al target di invocazione URL. Quando impostato con un valore di `false`, l'intestazione X- IBM -Client-Id HTTP non viene più soppressa dall'invio al target di invocazione URL. Questa proprietà è supportata solo da DataPower® Gateway (v5 compatible). Se stai utilizzando DataPower API Gateway , per ottenere la stessa funzionalità aggiungi una proprietà `header-control` alla configurazione della politica `invoke` nella definizione OpenAPI per la tua API, come nei seguenti esempi. Eliminare l'intestazione `X-Client-ID` nel modo seguente: `- invoke: target-url: http://myhostname/mypath header-control: type: blacklist values: - ^X-Client-ID$` Eliminare il parametro di query `userId` come segue: `- invoke: target-url: http://myhostname/mypath parameter-control: type: blacklist values: - ^userId$`	Booleano
x-ibm-gateway-optimize-invoke	N	Se è impostato su `false`, impedisce la sostituzione dell'ultima chiamata in una politica con il proxy. Qualsiasi valore diverso da `false` (non sensibile al maiuscolo / minuscolo) determinerà l'ultimo richiamo in una politica che potrebbe essere sostituito dal proxy quando l'API viene eseguita nel gateway.	Booleano
x-ibm-gateway-queryparam-encode-plus-char	N	Se impostato su un valore di `true`, tutti i caratteri + nei valori del parametro di query della destinazione - url delle politiche Invoke e Proxy vengono codificati in %2F. Il valore predefinito è `false`.	Booleano
x-ibm-gateway-api-enforce-response-limits	N	Se impostato su un valore di `true`, consente al programma di analisi JSON di essere applicato alla regola di risposta. Se la dimensione del corpo della risposta è superiore al limite del parser JSON impostato nel dominio DataPower , viene restituito un codice di stato di 500. Nota: la proprietà x-ibm-gateway-api-enforce-response-limits è supportata da DataPower Gateway (v5 compatible) ma non da DataPower API Gateway. Tuttavia, se utilizzi DataPower API Gateway, valuta la possibilità di utilizzare una politica Parse nel tuo assembly API per applicare tali limiti. Per informazioni sui diversi tipi di gateway, consultare la API Connect sezione «Tipi di gateway ».	Booleano
x-ibm-gateway-invoke-emulate-v4-soap-error	N	IBM API Management Version 4.0 avvia un DataPower errore quando un errore SOAP viene restituito da un servizio Web. IBM API Connect fornisce un meccanismo per rilevare errori SOAP e non avvia un errore DataPower . Per la compatibilit ... con le API sviluppate in IBM API Management Version 4.0, impostare questa propriet ... su `true` solo nel caso in cui un'estensione gateway prevede di gestire un errore SOAP in una regola di post - errore. Il valore predefinito è `false`. Nota: questa proprietà è obsoleta a favore di x-ibm-gateway-invoke-emulate-v4-invoke-error.	Booleano
x-ibm-gateway-invoke-keep-payload	N	Se impostato su un valore di `true`, la politica di invocazione invia un payload su un metodo DELETE dell' HTTP. Questa proprietà è disponibile per l'uso con IBM DataPower Gateway versione 7.7.1.1 e e successive. Il valore predefinito è `false`.	Booleano
x-ibm-gateway-invoke-emulate-v4-invoke-error	N	IBM API Management Version 4.0 avvia un DataPower errore quando viene restituito un errore del server di backend, un errore SOAP restituito da un servizio web o un errore JSON o XML (non SOAP) da un servizio restful. IBM API Connect fornisce un meccanismo per rilevare gli errori SOAP e gli errori operativi e non avvia un errore DataPower quando si verificano. Se non è configurata alcuna politica di cattura, viene generato un messaggio di errore generico. Per compatibilità con le API sviluppate in IBM API Management Version 4.0, impostare questa proprietà su `true` solo nel caso in cui un'estensione gateway prevede di gestire un errore del server di backend in una regola di post - errore dell'estensione del gateway o se il client dell'API prevede che venga restituito l'errore del server di backend. Il valore predefinito è `false`.	Booleano

Un elenco di proprietà API relative alla mappa che controllano il comportamento della politica della mappa.

Tabella 2. Proprietà che controllano le impostazioni della mappa
Proprietà	Obbligatorio	Descrizione	Tipo di dati
x-ibm-gateway-map-array-first-element-value	N	In IBM API Management Version 4.0, se un valore di origine della mappatura proviene da un array, viene emesso solo il primo valore. In API Connect, il comportamento predefinito è quello di restituire un array di tutti i valori dell'elemento array. Per mantenere la compatibilità con IBM API Management Version 4.0, impostare questa proprietà API su `true` per restituire solo il valore del primo elemento dell'array.	Booleano
x-ibm-gateway-map-resolve-apic-variables	N	Per impostazione predefinita, qualsiasi variabile API Connect trovata nella configurazione dell'associazione viene risolta. Ad esempio, `$(request.headers.content-type)` si risolve nell'intestazione del tipo di contenuto della richiesta. Poiché la ricerca di variabili in ogni propriet ... della mappa pu essere intensiva di CPU, Š possibile scegliere di non risolvere le variabili impostando questa propriet ... API su `false`. Se questa proprietà non è configurata o è impostata su un altro valore, il comportamento esistente per la ricerca di queste variabili continua. Si noti che l'utilizzo della variabile all'interno di un frammento JavaScript del valore della mappa non viene modificato purché le variabili a cui si fa riferimento provengano da un input della mappa configurato.	Booleano
x-ibm-gateway-map-create-empty-array	N	Questa proprietà controlla il modo in cui la politica di associazione gestisce l'output di un array vuoto; può avere i seguenti valori: `all`: emettere tutti gli array vuoti, inclusi gli array child vuoti. Questo è il valore predefinito se la proprietà non è configurata o ha un valore non valido. `parent`: emette solo il valore dell'array vuoto della proprietà corrente. Le azioni di associazione child di questa proprietà non vengono tentate. `none`: impedisce la produzione di eventuali valori di array di output vuoti.	Stringa
x-ibm-gateway-optimize-schema-definition	N	Impostare il valore di questa proprietà su `true` per fornire un miglioramento delle prestazioni alla politica di associazione quando una definizione di schema molto complessa viene indicata da una definizione di output della politica; ad esempio, alcuni schemi molto complessi che vengono generati importando uno schema WSDL molto complesso. La politica di associazione crea un schema da una definizione API quando viene fornita una definizione di riferimento come valore dello schema. Se lo schema non ha riferimenti che generano un riferimento circolare, l'impostazione di questa proprietà su `true` potrebbe fornire un vantaggio in termini di prestazioni durante la generazione dello stesso schema che altrimenti sarebbe stato generato. Tuttavia, nei casi in cui lo schema è molto complesso, con molti riferimenti potenzialmente circolari, lo schema generato potrebbe essere diverso perché la gestione dello schema avanzato elabora i riferimenti circolari in modo diverso. In questi casi, quindi, è necessario esaminare l'output risultante per determinare se il beneficio delle prestazioni ottenuto non è a discapito di una modifica nell'output della politica della mappa. Il valore predefinito di questa proprietà è `false`, che conserva il comportamento e le prestazioni esistenti.	Booleano
x-ibm-gateway-map-null-value	N	Impostare il valore di questa propriet ... API su `true` per consentire a una propriet ... dai dati di input di una politica di associazione con un valore `null` di essere associata al documento di output. Per impostazione predefinita, una proprietà dai dati di input di una politica di associazione con un valore `null` non è associata al documento di output.	Booleano
x-ibm-gateway-map-resolve-xmlinput-datatypes	N	Gli elementi di input XML con dati numerici o booleani non hanno metadati per indicare se questi dati devono essere associati come valore stringa o come tipo di dati specifico. Se si imposta il valore di questa proprietà su `false`, gli elementi di input XML vengono sempre associati come una stringa. Se si imposta il valore su `true`, gli elementi di input XML numerici o booleani vengono associati come il tipo di dati corrispondente dallo schema di input. Il valore predefinito è `false`.	Booleano
x-ibm-gateway-map-xml-empty-element	N	Questa proprietà controlla il modo in cui la politica di associazione gestisce gli elementi vuoti di input XML e influenza l'output JSON quando il documento di input è XML; può avere i seguenti valori: `string`: il valore per un elemento XML vuoto è considerato una stringa vuota. Questo è il valore predefinito se la proprietà non è configurata o ha un valore non valido. `null`: il valore per un elemento XML vuoto è considerato nullo. Un'associazione di questo elemento a una proprietà di output JSON non si verifica a meno che la proprietà API x-ibm-gateway-map-null-value non sia specificata anche con un valore `true`. `none`: l'elemento XML vuoto viene ignorato. `string-badgerfish`: il valore per un elemento XML vuoto è considerato una stringa vuota. Il valore stringa vuoto verrà inserito in una proprietà del valore badgerfish JSON. `null-badgerfish`: il valore per un elemento XML vuoto è considerato nullo. Il valore null verrà inserito in una proprietà del valore badgerfish JSON. Un'associazione di questo elemento a una proprietà di output JSON non si verifica a meno che la proprietà API `x-ibm-gateway-map-null-value` non sia specificata anche con un valore `true`.	Booleano
x-ibm-gateway-schema-definition-reference-limit	N	Impostare il valore di questa proprietà su un valore intero che specifichi il numero massimo consentito di iterazioni di una definizione di schema circolare. Il valore predefinito è 1, che significa che le definizioni di schemi circolari non vengono seguite. Il valore massimo possibile è 5. Se si specifica un valore maggiore di 5, viene assunto un valore pari a 5. Se si specifica un valore non numerico, viene utilizzato il valore 1.	Stringa
x-ibm-gateway-map-emulate-v4-default-required-properties	N	Impostare questa proprietà su true per avere valori predefiniti generati nell'output per le proprietà richieste che non sono associate o per cui non sono presenti dati di input, nei seguenti casi specifici: Un array è costituito da oggetti che contengono una o più proprietà richieste. Un oggetto facoltativo ha una o più proprietà child richieste. Per impostazione predefinita, queste proprietà richieste non sono presenti nell'output. Se si imposta la proprietà API `x-ibm-gateway-map-emulate-v4-default-required-properties` su `true`, queste proprietà richieste saranno presenti nell'output. Se lo schema di output definisce una proprietà `default` per la proprietà di output, viene utilizzato il valore predefinito specificato, altrimenti viene assegnato un valore predefinito in base al tipo di dati, come segue: Stringa: stringa vuota ("") Numero: 0 Booleano: false Oggetto: oggetto vuoto Array: array vuoto Esempio 1 I dati di immissione hanno il seguente array di oggetti: `[{“a”: “value1”}, {“a”: “value2", "b": “value3”}]` Lo schema di output definisce l'oggetto di output come avente due proprietà, `a` e `b`, di cui `b` è richiesto. La politica di associazione definisce le seguenti associazioni: Da `input.array.a` a `output.array.a` Da `input.array.b` a `output.array.b` Se la proprietà API `x-ibm-gateway-map-emulate-v4-default-required-properties` è impostata su `true`e `b` non è associato o non ha dati di input presenti, a `b` viene assegnato un valore predefinito di una stringa vuota e l'output è il seguente: `[{“a”: “value1", "b": ""}, {"a": "value2", "b": "value3"}]` Esempio 2 Lo schema di output definisce la struttura seguente: `{"a" : {"b" : {"c" : "value1", "d" : "value2"} } }` La proprietà `b` è facoltativa ma la proprietà `d` all'interno di `b` è obbligatoria. La politica di associazione definisce un'associazione a `output.a.b.c`. Se la proprietà API `x-ibm-gateway-map-emulate-v4-default-required-properties` è impostata su `true`e `d` non è associato, a `d` viene assegnato un valore predefinito di una stringa vuota e l'output è il seguente: `{"a" : {"b" : {"c" : "value1", "d" : ""} } }` Se la proprietà dell'API `x-ibm-gateway-map-emulate-v4-default-required-properties` non è specificata o non ha un valore `true`, queste proprietà richieste non vengono create nell'output con i relativi valori predefiniti.	Booleano
x-ibm-gateway-map-post-process-json-output	N	Impostare il valore di questa proprietà su `true` per abilitare la post - elaborazione dell'output JSON associato. La post-elaborazione dell'output JSON utilizzerà lo schema di output per garantire che i valori della proprietà siano dello stesso tipo di quello definito nello schema. Inoltre normalizzerà i valori della proprietà di output che hanno una sintassi JSON Badgerfish a causa dell'associazione di oggetti di un input XML. Impostare il valore su `false` per nessuna post - elaborazione dell'output JSON associato. Il valore predefinito è `false`.	Booleano
x-ibm-gateway-map-emulate-v4-empty-json-object	N	Se un'associazione ha esito negativo perché il relativo input non è presente e non è configurata alcuna associazione predefinita, il comportamento predefinito è di non apportare alcuna modifica all'associazione di output. Impostare il valore di questa proprietà su `true` per creare un oggetto vuoto per l'elemento principale dell'associazione di destinazione, emulando il comportamento di IBM API Management Version 4.0. Esempio La politica di associazione definisce un'associazione a `output.a.b.c`. Se sono presenti dati di input, l'output è il seguente: `{ "a": { "b": { "c": "inputvalue" } } }` Se non sono presenti dati di input e la proprietà API `x-ibm-gateway-map-emulate-v4-empty-json-object` è impostata su `true`, l'output è il seguente: `{ "a": { "b": { } } }` Le proprietà `a` e `b` vengono create, ma il valore di `b` è un oggetto vuoto. Il valore predefinito è `false`.	Booleano

Un elenco delle proprietà API relative al proxy che controllano il comportamento della politica del proxy.

Tabella 3. Proprietà che controllano la politica di proxy
Proprietà	Obbligatorio	Descrizione	Tipo di dati
x-ibm-gateway-proxy-suppress-clientid	N	Un'impostazione di `false` attiva l'iniezione dell'intestazione X- IBM -Client-Id HTTP (se specificata nella richiesta API) o del parametro di query `client_id` nella richiesta URL, all'URL di destinazione del proxy. Se non specificato o impostato con il valore `true`, elimina l'invio di questo parametro all'url di destinazione del proxy. Questa proprietà è supportata solo da DataPower Gateway (v5 compatible). Se stai utilizzando DataPower API Gateway , per ottenere la stessa funzionalità aggiungi una proprietà `header-control` alla configurazione della politica `invoke` nella definizione OpenAPI per la tua API, come nei seguenti esempi. Eliminare l'intestazione `X-Client-ID` nel modo seguente: `- proxy: target-url: http://myhostname/mypath header-control: type: blacklist values: - ^X-Client-ID$` Eliminare il parametro di query `userId` come segue: `- proxy: target-url: http://myhostname/mypath parameter-control: type: blacklist values: - ^userId$`	Booleano
x-ibm-gateway-optimize-invoke	N	Se è impostato su `false`, impedisce la sostituzione dell'ultima chiamata in una politica con il proxy. Qualsiasi valore diverso da `false` (non sensibile al maiuscolo / minuscolo) determinerà l'ultimo richiamo in una politica che potrebbe essere sostituito dal proxy quando l'API viene eseguita nel gateway.	Booleano
x-ibm-gateway-queryparam-encode-plus-char	N	Se impostato su un valore di `true`, tutti i caratteri + nei valori del parametro di query della destinazione - url delle politiche Invoke e Proxy sono codificati in %2F. Il valore predefinito è `false`.	Booleano
x-ibm-gateway-api-enforce-response-limits	N	Se impostato su un valore di `true`, consente al programma di analisi JSON di essere applicato alla regola di risposta. Se la dimensione del corpo della risposta è superiore al limite del parser JSON impostato nel dominio DataPower , viene restituito un codice di stato di 500.	Booleano

Un elenco di proprietà API che controllano il comportamento della politica del limite di frequenza.

Tabella 4. Proprietà che regolano la politica di limitazione della frequenza
Proprietà	Obbligatorio	Descrizione	Tipo di dati
x-ibm-gateway-emulate-v4-plan-rate-limit	N	Per impostazione predefinita in IBM API Connect Version 10, se configuri un limite di frequenza solo per un piano e non per le operazioni API all'interno del piano, viene impostata una singola soglia del limite di frequenza per l'API nel suo insieme, indipendentemente dall'operazione richiesta nell'API. Questo comportamento differisce da IBM API Management Version 4.0 dove il limite di velocità è impostato individualmente per ogni operazione nell'API. Per modificare il comportamento della Versione 10 per emulare il comportamento della Versione 4.0 , impostare questa proprietà API sul valore `true`.	Booleano

Un elenco di proprietà API che controllano il comportamento di più politiche.

Tabella 5. Proprietà che controllano più criteri
Proprietà	Obbligatorio	Descrizione	Tipo di dati
x-ibm-gateway-sourcecode-resolve-apic-variables	N	Se impostato su `true`, i riferimenti della variabile API Connect vengono risolti. Impostare su `false` se si desidera che la politica ignori i riferimenti della variabile API Connect . Il valore predefinito è `true`. Questa proprietà si applica alle politiche seguenti: Associazione GatewayScript XSLT se passa a Nota: questa impostazione della proprietà viene sovrascritta dall'impostazione della proprietà dell'API x-ibm-gateway-map-resolve-apic-variables per la politica di associazione.	Booleano
x-ibm-gateway-api-json-parse-error-handling	N	Se un payload di richiesta o risposta API include un contenuto JSON valido che contiene caratteri che non possono essere rappresentati nella sintassi interna XML JSONX utilizzata da DataPower Gateway, impostare questa proprietà su `escape-unicode` per consentire l'accettazione del payload senza errori di analisi. Se questa proprietà non è configurata o è impostata su un altro valore, il payload viene rifiutato come JSON non valido. Questa proprietà si applica al payload della richiesta API e al payload della risposta API quando `x-ibm-gateway-api-enforce-response-limits` è abilitato.	Stringa
x-ibm-gateway-framework-preserve-escaped-reverse-solidus	N	Per impostazione predefinita, la stringa `\\` in una proprietà della politica viene convertita in un singolo carattere `\` . Impostare questa proprietà su `true` per conservare la stringa `\\`.	Booleano
x-ibm-gateway-inspect-request-headers	N	Provoca un'ispezione delle intestazioni dell' HTTP e nella richiesta API per verificare la presenza di caratteri nei valori dell'intestazione che sono caratteri XML non validi; può avere i seguenti valori: `default`: non è presente alcuna ispezione per questi caratteri nei valori di intestazione. Se presente, la richiesta API fallisce con un errore 500 Internal Server Error ( HTTP ). `sanitize`: qualsiasi carattere XML non valido nei valori di intestazione viene sostituito con un carattere `?` . L'elaborazione API continuerà. Qualsiasi API che tenta di leggere `request.headers.<headername>` visualizzerà il carattere `?` nel valore. Tuttavia, le intestazioni del protocollo originali che rappresentano `message.headers` avranno ancora il carattere originale, che verrà inviato a un server di backend proxy o di richiamo. `bad-request`: ci sarà un'ispezione per questi caratteri nei valori di intestazione. Se presente, la richiesta API fallisce con un errore 400 Bad Request ( HTTP ). Il valore predefinito è `default`.	Booleano