Metodo api_post()

Invia una richiesta PUT all'API di HighBond.

Sintassi

hcl.api_post("Dettagli della richiesta API di HighBond", data = request_payload)

Parametri

Nome Descrizione
Dettagli della richiesta API di HighBond

Dettagli della richiesta per la risorsa Diligent One.

hcl.api_post fornisce automaticamente in background la parte standard dei dettagli della richiesta. Non è necessario specificare esplicitamente questi elementi di richiesta a meno che non si desideri sovrascrivere un valore predefinito:

  • informazioni sull'host

  • Area di Diligent One

  • ID istanza Diligent One (ID dell'organizzazione)

  • informazioni sull'intestazione

Per la sintassi della richiesta per una risorsa Diligent One specifica, consultare il Riferimento alle API di HighBond.

Nota

Se si specificano esplicitamente le informazioni sull'host, è necessario utilizzare il protocollo HTTPS per connettersi all'API di HighBond. Ad esempio: https://apis-us.highbond.com
data = request_payload

I dati da inviare al server API di Diligent One.

I dati del carico utile devono essere formattati come JSON.

Restituisce

Oggetto di risposta dal server API di HighBond.

Esempi

Creare una issue in un progetto Diligent One

Si crea un payload di richiesta che utilizza la formattazione JSON e si assegna il payload alla variabile payload. Si utilizza quindi il metodo hcl.api_post e si fa riferimento alla variabile payload nel metodo per creare una issue nel progetto con ID 19756.

Consiglio

Per creare rapidamente la sintassi del payload, copiare il blocco di sintassi del payload appropriato dal Riferimento alle API di HighBond. Dopo aver copiato il blocco del payload, è possibile rimuovere le coppie chiave-valore che si intende lasciare vuote.

payload = {"data":
        { 
            "type": "issues",
            "attributes": {
                "description": "Description of issue",
                "owner": "Jane Sleaman",
                "deficiency_type": "Deficiency",
                "title": "Data retention and backup",
                "severity": "High",
                "published": True,
                "identified_at": "2021-11-01T18:15:30Z"
                    }
                }
            }

hcl.api_post("projects/19756/issues", data = payload)

Osservazioni

Autenticazione

Tutte le richieste API di HighBond richiedono l'autenticazione. Per accedere all'API,occorre essere un amministratore di sistema in almeno un'istanza Diligent One.

Per eseguire l'autenticazione, usare Launchpad per creare un token API di HighBond per l'account. Il token è una stringa che autentica l'utente e consente di accedere in modo sicuro all'API di HighBond. Per ricevere assistenza nella creazione di un token, consultare Creare e gestire i token di accesso Diligent One.

Utilizzare un token API di HighBond con metodi di API di HighBond

Per utilizzare un token API di HighBond con i metodi di API di HighBond, è necessario assegnare il token a una variabile HCL denominata v_hb_token. Una volta assegnato, il token viene automaticamente utilizzato per l'autenticazione in background, senza che sia necessario specificarlo esplicitamente nello script Diligent One. Per ottenere informazioni sull'assegnazione del token alla variabile, consultare Utilizzare la finestra Variabili per definire una variabile HCL.

Token utente di sistema

I clienti che hanno acquistato kit di strumenti specifici Diligent One hanno anche la possibilità di autenticarsi utilizzando un token utente di sistema generico anziché un token associato a un account utente specifico.

Specificare solo la parte univoca dell'URL della risorsa

Quando si utilizza un metodo API di HighBond, è necessario specificare solo la parte univoca, o endpoint, dell'URL della risorsa Diligent One. Non è necessario specificare la parte comune (URL di base) o l'ID dell'istanza di Diligent One su cui si sta lavorando. Queste informazioni vengono fornite automaticamente in background.

Ad esempio, se si lavora su un'istanza Diligent One con ID 1000236, entrambe queste richieste API restituiscono una risposta identica. Entrambi elencano tutte le issue del progetto 19756.

hcl.api_get("projects/19756/issues")
hcl.api_get("https://apis.highbond.com/v1/orgs/1000236/projects/19756/issues")

Consultare il Riferimento alle API di HighBond

La sintassi della richiesta per ogni risorsa Diligent One è disponibile nel Riferimento alle API di HighBond. Ecco, ad esempio, la sintassi della richiesta per ottenere l'elenco delle issue in un progetto.

Se si utilizza un metodo HCL per effettuare la richiesta, è possibile iniziare a specificare la sintassi in projects/....

Se si effettua la richiesta dall'esterno di Diligent One, è necessario specificare l'intero URL della risorsa, a partire dal protocollo ( https://... ).

Utilizzare una variabile nell'URL della risorsa

Invece di specificare un ID letterale in un URL di risorsa, si potrebbe avere un codice che richiede l'utilizzo di una variabile nell'URL. L'URL della risorsa è formattato come una stringa, quindi per incorporare una variabile nella stringa è necessario utilizzare una delle tecniche Python illustrate di seguito.

È possibile utilizzare una f-string Python:

v_project_id = "19756"
hcl.api_get(f"projects/{v_project_id}/issues")

È possibile utilizzare la concatenazione di stringhe Python:

v_project_id = "19756"
hcl.api_get("projects/" + v_project_id + "/issues")