Metodi operativi

Questa sezione descrive i parametri operativi comuni gestiti dall'API del servizio Web IPS.

Per una descrizione completa di ciascun parametro di operazione, vedi Parametri di funzionamento.

Maniglie: Informazioni

Gestisce i riferimenti agli oggetti IPS restituiti da alcune operazioni API. Puoi anche passare gli handle come parametri alle chiamate di operazione successive. Gli handle sono tipi di dati stringa ( xsd:string).

Le maniglie sono destinate all'uso solo durante una singola sessione dell'applicazione. Inoltre, devi rendere persistenti gli handle perché il loro formato può cambiare tra le versioni IPS. Quando si scrivono applicazioni interattive, si implementano i timeout delle sessioni ed eliminano tutti gli handle tra le sessioni, in particolare dopo un aggiornamento IPS. Quando si scrivono applicazioni non interattive, chiamare le operazioni appropriate per recuperare gli handle ogni volta che l'applicazione viene eseguita. I seguenti esempi di codice Java/Axis2 mostrano un’esecuzione del codice errata e corretta:

Codice di handle non corretto

Questo esempio di codice non è corretto perché contiene un valore hardcoded (555) per l'handle dell'azienda.

SearchAssetsParam searchParam = new SearchAssetsParam(); searchParam.setCompanyHandle("555");// INCORRECT
searchParam.setFolder("myFolder");
SearchAssetsReturn retVal = ipsApi.searchAssets(searchParam, authHeader);

Codice di gestione corretto

Questo esempio di codice è corretto perché chiama getCompanyInfo per restituire un handle valido. Non si basa su un valore hardcoded. Utilizza questo metodo o un altro equivalente API IPS per restituire l’handle richiesto.

GetCompanyInfoParam companyInfoParam = new GetCompanyInfoParam();
companyInfoParam.setCompanyName("My Company"); GetCompanyInfoReturn companyInfoReturn = ipsApi.getCompanyInfo(companyInfoParam, authHeader);
String companyHandle = companyInfoReturn.getCompanyInfo().getCompanyHandle();
SearchAssetsParam searchParam = new SearchAssetsParam(); searchParam.setCompanyHandle(companyHandle); //CORRECT
searchParam.setFolder("myFolder");
SearchAssetsReturn retVal = ipsApi.searchAssets(searchParam, authHeader);

Tipi di handle comuni

companyHandle

La maggior parte delle operazioni richiede di impostare un contesto aziendale trasmettendo un companyHandle parametro . L'handle della società è un puntatore restituito da alcune operazioni, ad esempio getCompanyInfo, addCompanye getCompanyMembership.

userHandle

La userHandle è un parametro facoltativo per le operazioni che hanno come target un utente specifico. Per impostazione predefinita, queste operazioni sono indirizzate all'utente chiamante (l'utente le cui credenziali vengono passate per l'autenticazione). Tuttavia, gli utenti amministratori con le autorizzazioni appropriate possono specificare un altro utente. Ad esempio, il setPassword normalmente imposta la password dell'utente autenticato, ma un amministratore può utilizzare il userHandle per impostare la password per un altro utente.

Per le operazioni che richiedono un contesto aziendale (utilizzando companyHandle ), gli utenti autenticati e target devono essere membri della società specificata. Per le operazioni che non richiedono un contesto aziendale, gli utenti autenticati e target devono essere entrambi membri di almeno una società comune.

Le seguenti operazioni possono recuperare gli handle utente:

getUsers
getAllUsers
getUserInfo
getCompanyMembers
getGroupMembers
addUser

accessUserHandle e accessGroupHandle

Per impostazione predefinita, le operazioni che richiedono autorizzazioni di accesso (lettura, scrittura, eliminazione) operano nel contesto delle autorizzazioni dell'utente chiamante. Alcune operazioni consentono di modificare questo contesto con accessUserHandle o accessGroupHandle parametro . La accessUserHandle consente a un amministratore di rappresentare un altro utente. La accessGroupHandle consente al chiamante di funzionare nel contesto di un gruppo di utenti specifico.

responseFieldArray e excludeFieldArray

Alcune operazioni consentono al chiamante di limitare quali campi sono inclusi nella risposta. La limitazione dei campi può contribuire a ridurre il tempo e la memoria necessari per elaborare la richiesta e ridurre le dimensioni dei dati di risposta. Il chiamante può richiedere un elenco specifico di campi passando un responseFieldArray o con un elenco enumerato di campi esclusi tramite il excludeFieldArray parametro .

Entrambi responseFieldArray e excludeFieldArray specificare i campi utilizzando un percorso nodo separato da /. Ad esempio, per specificare che searchAssets restituisce solo il nome, la data dell’ultima modifica e i metadati per ogni risorsa fanno riferimento ai seguenti elementi:

<responseFieldArray>
   <items>assetArray/items/name</items>
   <items>assetArray/items/lastModified</items>
   <items>assetArray/items/metadataArray</items>
</responseFieldArray>

Allo stesso modo, per restituire tutti i campi (ad eccezione delle autorizzazioni):

<excludeFieldArray>
   <items>assetArray/items/permissions</items>
</excludeFieldArray>

I percorsi dei nodi sono relativi alla radice dei nodi restituiti. Se si specifica un campo di tipo complesso senza alcun sottoelemento (ad esempio, assetArray/items/imageInfo), vengono inclusi tutti i relativi sottoelementi. Se specifichi uno o più elementi secondari in un campo di tipo complesso (ad esempio, assetArray/items/imageInfo/originalPath), vengono inclusi solo i sottoelementi.

Se non includi responseFieldArray o excludeFieldArray in una richiesta vengono restituiti tutti i campi.

Lingua

A partire da IPS 4.0, l’API IPS supporta l’impostazione del contesto internazionale di un’operazione passando il authHeader parametro locale. Se il parametro locale non è presente, l’intestazione HTTP Accept-Language viene utilizzato. Se questa intestazione non è presente, verranno utilizzate le impostazioni internazionali predefinite per il server IPS.

Alcune operazioni utilizzano anche parametri internazionali espliciti, che possono essere diversi dal contesto internazionale delle operazioni. Ad esempio, il submitJob l'operazione richiede un locale che imposta le impostazioni internazionali utilizzate per la registrazione dei processi e la notifica via e-mail.

I parametri internazionali utilizzano il formato <language_code>[-<country_code>]

Se il codice della lingua è un codice a due lettere, minuscolo, specificato dalla norma ISO-639 e il codice del paese opzionale è un codice a due lettere, maiuscolo e minuscolo specificato dalla norma ISO-3266. Ad esempio, la stringa locale per Inglese USA è en-US.