api_get() メソッド

HighBond API に GET 要求を送信します。

構文

hcl.api_get("HighBond API 要求詳細")

パラメーター

名前 説明
HighBond API 要求詳細

Diligent One リソースの要求詳細。

hcl.api_get は要求詳細の標準部分を自動的にバックグラウンドで提供します。デフォルト値を上書きしたい場合を除き、これらの要求要素を明示的に指定する必要はありません。

  • ホスト情報

  • Diligent One のリージョン

  • Diligent One インスタンス ID(組織 ID)

  • ヘッダー情報

特定の Diligent One リソースの要求構文については、HighBond API リファレンスを参照してください。

メモ

ホスト情報を明示的に指定する場合、HighBond API との接続には HTTPS プロトコルを使用する必要があります。例:https://apis-us.highbond.com

戻り値

HighBond API サーバーからの応答オブジェクト。

基本的な例

メモ

hcl.api_get() メソッドは、HighBond API サーバーから返されるすべてのものを含む応答オブジェクトを返します。応答オブジェクトには、メタデータとデータの両方が含まれます。通常、Python/HCL スクリプトで使用できるデータを抽出するために、応答オブジェクトに後続の処理を適用する必要があります。詳細については、高度な例を参照してください。

Diligent One インスタンスのすべてのプロジェクトの一覧を取得します

作業している Diligent One インスタンスのすべてのプロジェクトの一覧を返します。

hcl.api_get("projects")

Diligent One リザルト アプリですべてのコレクションの一覧を取得します

作業している Diligent One インスタンス内のすべてのリザルトコレクションの一覧を返します。

hcl.api_get("collections")

プロジェクトのすべての問題の一覧を取得します

ID 19756 のプロジェクトのすべての問題の一覧を返します。

hcl.api_get("projects/19756/issues")

問題の一覧を取得し、応答のフィールドを制限します

ID 19756 のプロジェクトのすべての問題の一覧を返し、各問題の指定されたフィールドのみを返します。

hcl.api_get("projects/19756/issues?fields[issues]=title,description,creator_name,created_at,updated_at,owner")

高度な例

HighBond API サーバーから返された応答オブジェクトの問題のリストにアクセスします。

通常、含まれるデータを処理できるように、HighBond API サーバーから返された応答オブジェクトを操作する必要があります。

ID 19756 のプロジェクトのすべての問題の一覧を含む応答オブジェクトを返します。

response_object = hcl.api_get("projects/19756/issues")

Python 要求ライブラリから .json() メソッドを使用して、応答オブジェクトの JSON エンコードされた部分を Python 辞書に抽出します。これで、Python/HCL スクリプトで問題データを処理できるようになりました。

import requests
hb_issues_dict = response_object.json()

また、上記の 2 つの操作を次のように単一のステップで行うこともできます。

import requests
hb_issues_dict = hcl.api_get("projects/19756/issues").json()

Python 辞書を画面に出力して内容を確認できます。追加の書式設定がない場合、辞書は改行も、入れ子の要素を示すインデントもなしに表示されます。

print(hb_issues_dict)

Python JSON ライブラリから .dumps() メソッドを使用して、辞書の内容がより読みやすくなるように追加の書式設定を適用します。

import json
hb_issues_dict_formatted = json.dumps(hb_issues_dict, indent=4)
print(hb_issues_dict_formatted)

書式設定された出力の例:

{
    "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": "<p>Data retention and backup policy does not exist</p>\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
    }
}

備考

認証

すべての HighBond API 要求は認証が必要です。API にアクセスするには、少なくとも 1 つの Diligent One インスタンスのシステム管理者である必要があります。

認証するには、Launchpad を使用して、アカウントの HighBond API トークンを作成します。トークンは、認証を行い、安全に HighBond API にアクセスできるようにする文字列です。トークンの作成のヘルプについては、HighBond アクセストークンの作成と管理を参照してください。

HighBond API メソッドで HighBond API トークンを使用する

HighBond API メソッドで HighBond API トークンを使用するには、トークンを HCL 変数 v_hb_token に割り当てる必要があります。トークンが割り当てられた後は、自動的にバックグラウンドで認証に使用されます。Diligent One スクリプトで明示的に指定する必要はありません。変数へのトークンの割り当てについては、[変数]ウィンドウを使用して HCL 変数を定義するを参照してください。

システムユーザートークン

特定の Diligent One ツールキットを購入されたお客様は、特定のユーザーアカウントに関連付けられたトークンではなく、汎用システムユーザートークンを使用して認証することもできます。

リソース URL の一意の部分のみを指定する

HighBond API メソッドを使用するときには、Diligent One リソース URL の一意の部分(最後の部分)のみを指定する必要があります。共通部分(ベース URL)や作業している Diligent One インスタンスの ID を指定する必要はありません。この情報はバックグラウンドで自動的に入力されます。

たとえば、Diligent One インスタンス ID 1000236 で作業している場合は、これらの API 要求のいずれも同じ応答を返します。これらはいずれもプロジェクト 19756 のすべての問題の一覧を出力します。

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

HighBond API リファレンスを参照する

すべての Diligent One リソースの要求構文については、HighBond API リファレンスを参照してくださいたとえば、次に、プロジェクトの問題の一覧を取得する要求構文を示します。

HCL メソッドを使用して要求を作成している場合は、projects/... で構文の指定を開始できます。

Diligent One 外から要求を行っている場合は、リソース URL 全体を指定し、先頭にプロトコル (https://...) を指定する必要はありません。

リソース URL で変数を使用する

リソース URL でリテラル ID を指定するのではなく、URL で変数を使用する必要があるコードを作成することがあります。リソース URL の書式は文字列であるため、文字列に変数を組み込むには、次に示す Python 手法のいずれかを使用する必要があります。

Python f 文字列を使用できます。

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

Python 文字列連結を使用できます。

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