IBM Cloud Docs
Richiamo delle API REST del gestore code

Richiamo delle API REST del gestore code

IBM MQ offre una serie di API REST che forniscono un modo semplice per amministrare, testare e interagire con il tuo gestore code tramite script, applicazioni e programmi. In questa sezione, verranno forniti i requisiti per chiamare le API sul gestore code IBM, oltre a degli esempi che possono essere eseguiti direttamente dal tuo terminale ed essere facilmente convertiti in altri linguaggi di programmazione.

Un gestore code IBM ha 2 API REST disponibili per la chiamata:

  • API REST di amministrazione: consente di eseguire azioni amministrative sul gestore code
  • API REST di messaggistica: consente alle applicazioni di inviare e ricevere messaggi

Esistono alcune informazioni importanti quando si interagisce con il gestore code IBM:

  1. La porta del listener non è richiesta nell'URI per chiamare l'API REST
  2. Il nome host per chiamare il tuo gestore code deve iniziare con web-
  3. L'inizio del percorso nell'URI deve essere /ibmmq/rest
  4. L'API REST è sensibile al maiuscolo / minuscolo, ad esempio se il proprio gestore code è denominato QM1 e si utilizza l'API REST di gestione, nel percorso per l'amministratore è necessario eseguire /qmgr/QM1/...

Autenticazione del tuo client per richiamare le richieste dell'API REST

Esistono un paio di metodi per eseguire l'autenticazione con il tuo gestore code IBM su REST.

Il primo metodo prevede l'uso dell'autenticazione di base; questo è un metodo molto comune utilizzato per interagire con il gestore code su REST in quanto è facile da convertire in altri linguaggi ed è ottimo per i test.

Per ulteriori informazioni sull'utilizzo dell'autenticazione di base per eseguire l'autenticazione con il tuo gestore code, vedi qui.

Esempio: autenticazione con un gestore code IBM tramite autenticazione di base

  1. Richiama i tuoi nome utente MQ e chiave API dalla tua istanza del servizio in IBM Cloud, quindi esegui quanto segue:

    AUTH=`echo "<MQ_USERNAME>:<API_KEY>" | base64`

    MQ_USERNAME e API_KEY dipenderanno dall'API REST a cui si accede:

    • admin, devi aggiungere il tuo utente nella scheda delle autorizzazioni utente che ti genererà un nome utente MQ e utilizzerà la tua chiave API della piattaforma per IBM Cloud
    • di messaggistica, è necessario creare un'autorizzazione dell'applicazione nella scheda delle autorizzazioni dell'applicazione e utilizzare la chiave API e il nome utente MQ che genera per l'utente

  2. Passa il valore di AUTH nell'intestazione dell'autorizzazione delle tue richieste.

    curl -H "Authorization: Basic $AUTH" -H "ibm-mq-rest-csrf-token: value" https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v2/admin/qmgr/qm1

Il secondo metodo è l'autenticazione basata su token, che prevede l'interazione con l'API REST di accesso esposta dal gestore code. Questa API REST restituisce un cookie che può essere salvato in una variabile nel tuo script o nella tua applicazione oppure in un file di testo semplice che può essere utilizzato dalle successive richieste al tuo gestore code.

Una volta terminata l'interazione con il gestore code IBM su REST, l'API REST di accesso può essere utilizzata anche per revocare il token di accesso, richiedendo al client di recuperare un nuovo token di accesso prima di effettuare chiamate successive.

Per ulteriori informazioni su come utilizzare l'autenticazione basata su token per interagire con il tuo gestore code su REST, vedi qui.

Amministrazione del gestore code

L'API REST di amministrazione offre la possibilità di amministrare il gestore code, consentendoti di creare, recuperare, modificare ed eliminare le code.

La documentazione dell'API REST di amministrazione è disponibile qui.

Esempio: creazione di una coda in un gestore code IBM

Se hai effettuato l'autenticazione utilizzando l'autenticazione basata su token, specifica il punto in cui hai memorizzato il tuo cookie per identificarti come utente autenticato.

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/admin/action/qmgr/QM1/mqsc -H "Accept: application/json" -H "Content-Type: application/json" -H "ibm-mq-rest-csrf-token: value" --data '{
  "type": "runCommand",
  "parameters": {
    "command": "DEFINE QLOCAL(TEST.QUEUE)"
  }
}' -b cookiejar.txt

È quindi possibile visualizzare la coda creata eseguendo il seguente comando.

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/admin/action/qmgr/QM1/mqsc -H "Accept: application/json" -H "Content-Type: application/json" -H "ibm-mq-rest-csrf-token: value" --data '{
  "type": "runCommand",
  "parameters": {
    "command": "DISPLAY QLOCAL(TEST.QUEUE)"
  }
}' -b cookiejar.txt

Invio e ricezione di messaggi

L'API REST di messaggistica ti consente di inviare e recuperare i messaggi su una coda desiderata all'interno di un gestore code IBM.

La documentazione dell'API REST di messaggistica è disponibile qui.

Code non 'DEV.'

Se è stata creata una nuova coda il cui nome non inizia con 'DEV.' i record di autorizzazione predefiniti non verranno applicati. Pertanto, le applicazioni non disporranno delle autorizzazioni richieste per inviare o ricevere messaggi a questa coda. Consultare la guida Assegnazione dell'accesso utente / gruppo a una coda per ulteriori informazioni e per le operazioni richieste per configurare il record di autorizzazione richiesto per questa coda.

Esempio: inserimento di un messaggio su una coda in un gestore code IBM

Se hai effettuato l'autenticazione utilizzando l'autenticazione basata su token, specifica il punto in cui hai memorizzato il tuo cookie per identificarti come utente autenticato.

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/messaging/qmgr/qm1/queue/TEST.QUEUE/message -H "Content-Type: text/plain" -H "ibm-mq-rest-csrf-token: value" --data "hello world" -b cookiejar.txt

Per impostazione predefinita, tutti i messaggi inviati tramite l'API REST di messaggistica verranno trattati come non persistenti, indipendentemente dall'impostazione di persistenza predefinita della coda di destinazione. Per modificare il comportamento predefinito, è possibile includere un'intestazione facoltativa ibm-mq-md-persistence che deve essere specificata come uno dei seguenti valori:

  • persistente
  • nonPersistent

Per inviare un messaggio persistente, l'esempio precedente assume il seguente formato:

curl -X POST https://web-qm1-abcd.qm.eu-gb.appdomain.cloud/ibmmq/rest/v3/messaging/qmgr/qm1/queue/TEST.QUEUE/message -H "Content-Type: text/plain" -H "ibm-mq-rest-csrf-token: value" -H "ibm-mq-md-persistence: persistent" --data "hello world" -b cookiejar.txt

L'elenco completo delle intestazioni API REST di messaggistica è disponibile qui.