api_get()-Methode
Sendet eine GET-Anfrage an die HighBond-API.
Syntax
hcl.api_get ("Details der HighBond-API-Anfrage")
Parameter
| Name | Beschreibung |
|---|---|
| Details der HighBond-API-Anfrage |
Die Anfragedetails für die Diligent One-Ressource. hcl.api_get 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 |
Gibt zurück
Antwortobjekt von HighBond API-Server.
Beispiele
Einfache Beispiele
Hinweis
Die Methode hcl.api_get() gibt ein Antwortobjekt zurück, das alles enthält, was vom HighBond API-Server zurückgegeben wurde. Das Antwortobjekt enthält sowohl Metadaten als auch Daten. In der Regel müssen Sie nachfolgende Verarbeitungsschritte auf das Antwortobjekt anwenden, um Daten zu extrahieren, die Sie in einem Python/HCL-Skript verwenden können. Weitere Informationen finden Sie unter Weiterführende Beispiele.
Liste aller Projekte in einer Diligent One-Instanz erhalten
Gibt eine Liste aller Projekte in der Diligent One-Instanz zurück, in der Sie arbeiten:
hcl.api_get("projects")
Liste aller Sammlungen in der Diligent One-Ergebnisse-App erhalten
Gibt eine Liste aller Ergebnissammlungen in der Diligent One-Instanz zurück, in der Sie arbeiten:
hcl.api_get("collections")
Liste aller Probleme in einem Projekt erhalten
Gibt eine Liste aller Probleme im Projekt mit der ID 19756 zurück:
hcl.api_get("projects/19756/issues")
Liste der Probleme erhalten und die Felder in der Antwort begrenzen
Gibt eine Liste aller Probleme im Projekt mit der ID 19756 zurück, wobei bei jedem Problem nur die angegebenen Felder zurückgegeben werden:
hcl.api_get("projects/7718/issues?fields[issues]=title,description,creator_name,created_at,updated_at,owner")
Weiterführende Beispiele
Liste der Probleme im Antwortobjekt aufzurufen, die vom HighBond API-Server zurückgegeben wurden
In der Regel müssen Sie das vom HighBond API-Server zurückgegebene Antwortobjekt bearbeiten, damit Sie mit den enthaltenen Daten arbeiten können.
Gibt ein Antwortobjekt mit einer Liste aller Probleme im Projekt mit der ID 19756 zurück:
response_object = hcl.api_get("projects/19756/issues")
Verwendet die Methode .json() aus der Bibliothek Python-Anfragen, um den JSON-kodierten Teil des Antwortobjekts in ein Python-Wörterbuch zu extrahieren. Sie können jetzt mit den Problemdaten in einem Python/HCL-Skript arbeiten.
import requests hb_issues_dict = response_object.json()
Sie können auch beide Abläufe in einem Schritt ausführen:
import requests
hcl.api_get("projects/19756/issues")
Sie können das Python-Wörterbuch auf dem Bildschirm ausgeben, um den Inhalt zu sehen. Ohne zusätzliche Formatierung wird das Wörterbuch ohne Zeilenumbrüche oder Einrückungen zum Abheben verschachtelter Elemente angezeigt:
print(hb_issues_dict)
Verwendet die Methode .dumps() aus der Python JSON-Bibliothek, um zusätzliche Formatierung anzuwenden, damit der Wörterbuchinhalt besser lesbar ist.
import json hb_issues_dict_formatted = json.dumps(hb_issues_dict, indent=4) print(hb_issues_dict_formatted)
Beispiel der formatierten Ausgabe:
{
"data": [
{
"id": "52983",
"type": "issues",
"attributes": {
"title": "Data retention and backup",
"description": null,
"creator_name": null,
"created_at": "2015-05-08T20:59:34Z",
"updated_at": "2016-11-17T18:44:59Z",
"position": 3,
"owner": "Jane Sleaman",
"recommendation": "",
"deficiency_type": "Deficiency",
"severity": "High",
"published": true,
"identified_at": "2015-05-08T20:59:34Z",
"reference": null,
"reference_prefix": "1-A",
"risk": "Data retention and backup policy does not exist\r\n",
"scope": null,
"escalation": null,
"cause": "",
"effect": "",
"cost_impact": 3000.0,
"executive_summary": null,
"executive_owner": null,
"project_owner": null,
"closed": false,
"remediation_status": null,
"remediation_plan": null,
"remediation_date": null,
"actual_remediation_date": null,
"retest_deadline_date": null,
"actual_retest_date": null,
"retesting_results_overview": null,
"custom_attributes": []
},
"relationships": {
"project": {
"data": {
"id": "19756",
"type": "projects"
}
},
"owner_user": {
"data": {
"id": "HWF9X5jpXsS",
"type": "users"
}
},
"executive_owner_user": {
"data": null
},
"project_owner_user": {
"data": null
},
"creator_user": {
"data": null
}
}
}
],
"links": {
"prev": null,
"next": null
}
}
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")
