api_post()-Methode
Sendet eine POST-Anfrage an die HighBond-API.
Syntax
hcl.api_post("Details der HighBond-API-Anfrage", data = Anfrage-Payload)
Parameter
| Name | Beschreibung |
|---|---|
| Details der HighBond-API-Anfrage |
Die Anfragedetails für die Diligent One-Ressource. hcl.api_post Gibt automatisch den Standardteil der Anfragedetails im Hintergrund an. Diese Anfragebestandteile müssen Sie nicht explizit angeben, es sei denn, Sie möchten einen Standardwert überschreiben.
Die Anfragesyntax einer bestimmten Diligent One-Ressource finden Sie in der HighBond-API-Referenz. Hinweis Wenn Sie explizit Host-Informationen angeben, müssen Sie das HTTPS-Protokoll verwenden, um sich mit der HighBond-API zu verbinden. Beispielsweise: https://apis-us.highbond.com |
| data = Anfrage-Payload |
Die Daten, die an den Diligent One API-Server gesendet werden sollen. Die Payload-Daten müssen als JSON-Daten formatiert sein. |
Gibt zurück
Antwortobjekt von HighBond API-Server.
Beispiele
In einem Diligent One-Projekt ein Problem erstellen
Sie erstellen eine Anfrage-Payload mit JSON-Formatierung und weisen die Payload der payload-Variablen zu. Danach nutzen Sie die Methode hcl.api_post und geben in der Methode die payload-Variable an, um ein Problem im Projekt mit der ID 19756 zu erstellen.
Tipp:
Um schnell eine Payload-Syntax zu erstellen, kopieren Sie den entsprechenden Payload-Syntax-Block aus der HighBond API Reference. Nach dem Kopieren des Payload-Blocks können Sie die Wertepaare entfernen, die leer bleiben sollen.
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)
Bemerkungen
Authentifizierung
Alle HighBond-API-Anfragen erfordern eine Authentifizierung. Um auf die API zuzugreifen, müssen Sie mindestens in einer Diligent One-Instanz ein Systemadministrator sein.
Zur Authentifizierung verwenden Sie Launchpad, womit Sie einen HighBond-API-Token für Ihr Konto erstellen. Der Token ist eine Zeichenfolge, die Sie authentifiziert und Ihnen ermöglicht, sicher auf die HighBond-API zuzugreifen. Hilfe zum Erstellen von Token finden Sie unter HighBond-Zugriffstoken erstellen und verwalten.
HighBond-API-Token mit HighBond-API-Methoden verwenden
Um einen HighBond-API-Token mit den HighBond-API-Methoden zu verwenden, müssen Sie den Token einer HCL-Variable namens v_hb_token zuweisen. Sobald der Token zugewiesen ist, wird er automatisch zur Authentifizierung im Hintergrund verwendet, ohne dass er im Diligent One-Skript explizit festgelegt werden muss. Informationen über das Zuweisen des Tokens zu einer Variable finden Sie unter HCL-Variablen werden im Fenster „Variablen“ definiert..
Systembenutzertoken
Kunden, die bestimmte Diligent One-Toolkits gekauft haben, können sich auch mit einem generischen Systembenutzertoken anstatt einem Token für ein bestimmtes Benutzerkonto authentifizieren.
Lediglich den eindeutigen Teil der Ressourcen-URL angeben
Wenn Sie eine HighBond-API-Methode verwenden, müssen Sie lediglich den eindeutigen Teil der Diligent One-Ressourcen-URL angeben, also den Endpunkt. Den gemeinsamen Teil (die Basis-URL) oder die ID der Diligent One-Instanz, in der Sie arbeiten, müssen Sie nicht festlegen. Diese Informationen werden automatisch im Hintergrund angegeben.
Wenn Sie beispielsweise in einer Diligent One-Instanz mit der ID 1000236 arbeiten, liefern die beiden folgenden API-Anfragen dieselbe Antwort. Sie enthalten beide alle Probleme in Projekt 19756.
hcl.api_get("projects/19756/issues")hcl.api_get("https://apis.highbond.com/v1/orgs/1000236/projects/19756/issues")
HighBond-API-Referenz verwenden
Die Anfragesyntax für jede Diligent One-Ressource ist in der HighBond-API-Referenz verfügbar. Hier sehen Sie beispielsweise die Anfragesyntax, um eine Liste der Probleme innerhalb eines Projekts zu erhalten.
Wenn Sie eine HCL-Methode für diese Anfrage verwenden, können Sie unter projects/... beginnen, die Syntax anzugeben.
Falls Sie die Anfrage außerhalb von Diligent One stellen, müssen Sie die gesamte Ressourcen-URL angeben und dabei mit dem Protokoll ( https://... ) beginnen.
Variablen in einer Ressourcen-URL verwenden
Anstatt einer literalen ID ist in Ihrem Code unter Umständen die Verwendung einer Variable in der URL notwendig. Die Ressourcen-URL ist als Zeichenfolge formatiert. Um eine Variable in die Zeichenfolge einzubinden, müssen Sie also eine der folgenden dargestellten Python-Techniken verwenden.
Sie können einen f-String von Python verwenden:
v_project_id = "19756"
hcl.api_get(f"projects/{v_project_id}/issues")
Sie können die Zeichenfolgenverkettung von Python nutzen:
v_project_id = "19756"
hcl.api_get("projects/" + v_project_id + "/issues")
