HB_API_POST コマンド

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

構文

HB_API_POST HighBond API 要求 URL HEADERS ヘッダー情報 DATA ペイロードファイル PASSWORD 番号 <TO 回答ファイル>HighBond_API_request_URL

パラメーター

名前 説明
HighBond API 要求 URL

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

以下の詳細を要求 URL に含めます：

  • ホスト情報（Diligent One のリージョンを含む）

  • API バージョン番号 (現在のメジャーバージョン番号)

  • Diligent One インスタンス ID（組織 ID）

  • HighBond API エンドポイント名、および ID 番号などの追加のエンドポイント詳細

例：

"https://apis-us.highbond.com/v1/orgs/11594/robots"

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

HEADERS ヘッダー情報

要求ヘッダー情報。

ヘッダーで、HighBond API 要求のコンテンツの種類を指定します。

'{"content-type": "application/vnd.api+json"}'
DATA ペイロードファイル

要求ペイロードを含むファイルの名前。

要求ペイロードは Diligent One に送信するデータです。JSONファイルにデータを格納し、DATAを使用して HighBond API 要求のファイルを参照します。特定の Diligent One リソースのペイロードデータの構築については、HighBond API リファレンスを参照してください。

*.json ファイル拡張子を持つ引用符で囲まれた文字列としてペイロードファイルを指定します。例：

DATA "payload.json"

メモ

ロボットで実行するスクリプトの場合、アナリティクス ヘッダーで、DATA ペイロード ファイル パラメーターに対応する //FILE タグも指定する必要があります。例：

COMMENT
//ANALYTIC Test HB API コマンド
//FILE payload.json
END

ペイロード JSON ファイルを保存する場所

ペイロード JSON ファイルを保存する場所はスクリプトを実行する場所によって決まります。

Analytics でスクリプトを実行する

Analytics プロジェクトを含むフォルダーまたは別のフォルダーにペイロード JSON ファイルを保存できます。

プロジェクトフォルダー以外のフォルダーにファイルを保存する場合、ペイロードファイルにファイルパスとファイル名を含める必要があります。

DATA "C:\HighBond API payloads\payload.json"

ロボットでスクリプトを実行する

ペイロード JSON ファイルを、スクリプトを実行するロボットの［入力/出力］タブにアップロードします。スクリプトを実行する前に、ファイルがこのタブに存在している必要があります。

ペイロードファイルでファイル名のみを指定します。ファイルパスを指定しないでください。

PASSWORD 番号

使用するパスワード定義。

実際のパスワードを入力することを求めたり指定したりするのには、PASSWORD 番号の構文は使用しません。パスワード定義とは、以前に PASSWORD コマンドか SET PASSWORD コマンドを使用して入力または設定されたパスワードのことです。

番号はパスワード定義の番号です。たとえば、以前に 2 つのパスワードをスクリプトで設定したり入力したりしている場合、またはアナリティクス スクリプトをスケジュールしている場合、PASSWORD 2 により、2 番目のパスワードを使用することを指定します。

パスワードの入力または設定の詳細については、次を参照してください。

必須のパスワード値は、HighBond アクセストークンです。詳細については、パスワード定義の作成とパスワード値の指定を参照してください。

PASSWORD 番号は必要な場合と不要な場合があります。スクリプトを実行する環境によって異なります。　

スクリプトが実行される環境 PASSWORD 番号要件
Analytics

（オンライン アクティベーション）

PASSWORD 番号は不要です。

Windows レジストリに保管されている現在のユーザーの HighBond アクセストークンが自動的に使用されます
Analytics

（オフライン アクティベーション）

PASSWORD 番号は必要です。
ロボット
TO 回答ファイル

省略可能

要求の回答を含むファイルの名前。

*.json ファイル拡張子を持つ引用符で囲まれた文字列として回答ファイルを指定します。例：

TO "response.json"

回答 JSON ファイルを保存する場所。

回答 JSON ファイルを保存する場所はスクリプトを実行する場所によって決まります。

Analytics でスクリプトを実行する

デフォルトでは、回答 JSON ファイルは、Analytics プロジェクトが入っているフォルダーに保存されます。

ファイルを別の既存のフォルダーに保存するには、ファイルパスにその名前を含めます。

TO "C:\HighBond API responses\response.json"

ロボットでスクリプトを実行する

アナリティクス ヘッダーで //RESULT FILE タグを指定すると、回答 JSON ファイルは、ロボットでのそれぞれのタスク実行の出力として保存されます。

ファイル名のみを指定します。ファイルパスを指定しないでください。

例

Diligent One プロジェクトで問題を作成する

JSON 形式を使用する要求ペイロードを構築し、create_issue.json という名前のファイルにペイロードを保存します。HB_API_POST コマンドを使用して、コマンドでペイロードファイルを指定し、ID 19756 のプロジェクトに問題を作成します。

ヒント

ペイロード構文をすばやく構築するには、適切なペイロード構文ブロックを HighBond API リファレンスからコピーします。ペイロード ブロックをコピーした後、空のままにする予定のキーと値のペアを削除します。

HB_API_POST "https://apis-us.highbond.com/v1/orgs/11594/projects/19756/issues" HEADERS '{"content-type": "application/vnd.api+json"}' DATA "create_issue.json" PASSWORD 1 TO "hb_api_response.json"

create_issue.json の内容:

{
"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"
                }
    }
}

備考

パスワード定義の作成とパスワード値の指定

ロボットで HighBond API に要求を送信するスクリプトを実行する場合、要求を送信するコマンドとともにパスワード定義を含める必要があります。オフラインアクティベーションを使用する場合、同じ要件が Analytics で実行されるスクリプトに適用されます。

どの方法を用いてパスワード定義を作成したかにかかわらず、パスワードには値として HighBond アクセストークンを指定する必要があります。このトークンは Launchpad で生成できます。詳細については、HighBond アクセストークンを取得を参照してください。

パスワード定義方法

方法 説明

PASSWORD アナリティクス タグ

（ロボットで実行するスクリプト用）

PASSWORD アナリティクスタグを使用して、Diligent One に接続するための番号付けされたパスワード定義を作成した場合、スクリプトでパスワードの値が指定されません。ロボットでスクリプトを実行するタスクを作成すると、タスクデザイナーの入力フィールドで実際のパスワードを指定できます。

詳細については、PASSWORD アナリティクスタグを参照してください。

PASSWORD コマンド

（Analytics で実行するスクリプトでは、オフラインアクティベーション）

PASSWORD コマンドを使用して、Diligent One に接続するための番号付けされたパスワード定義を作成した場合、スクリプトでパスワードの値が指定されません。スクリプトで接続しようとすると、パスワードプロンプトが表示されます。

詳細については、PASSWORD コマンドを参照してください。

SET PASSWORD コマンド

（Analytics で実行するスクリプトでは、オフラインアクティベーション）

SET PASSWORD コマンドを使用して、Diligent One に接続するための番号付けされたパスワード定義を作成した場合、スクリプトでパスワードの値が指定されるため、パスワードプロンプトは表示されません。この方法は自動実行用に作成されたスクリプトに適していますが、スクリプトに実際のパスワードがクリアテキストで表示されるため、この状況には適していません。

詳細については、SET PASSWORD コマンドを参照してください。

HighBond アクセストークンを取得

注意

生成されるアクセストークンは Diligent One にサインインするために使用されるアカウントと一致します。他のユーザーが使用するスクリプトを作成する場合は、そのスクリプト内に自身のアクセストークンを指定することは不適切です。

アクセストークンはアカウントパスワードと同じように保護してください。

新しいアクセストークンを作成する理由がない場合は、既存のトークンを使用してください。既存のトークンが機能しない場合は、新しいトークンを作成してください。既存のトークンを使用すると、管理する必要があるトークン数が減ります。

  1. 次のいずれかを実行します。

    • Analytics メインメニューで［ツール］ > ［HighBond アクセストークン］を選択します。HighBond Access Token

    • スクリプト エディター内を右クリックし、［挿入 > HighBond トークン］を選択します。HighBond Token

    ［API トークンを管理］ページがお使いのブラウザーで開きます。最初に Diligent One にサインインすることを求められる場合があります。

    Analytics からの［API トークンを管理］ページへのアクセスが便利です。Diligent One にサインインし、Analytics を使用せずにユーザープロファイルからこのページにアクセスすることもできます。

  2. 次のいずれかを実行します。

    • 既存のトークンを使用する

      1. ［トークン］列で、使用するトークンをクリックします。

      2. Diligent One アカウントのパスワードを入力し、［確認Diligent One］をクリックします。

        マスクされていないトークンが表示されます。

      3. ［コピー ］をクリックしてトークンをコピーします。

        ヒント

        トークンが含まれているこのダイアログボックスは、そのトークンを貼り付けるまで閉じないでください。

    • 新しいトークンを作成する

      1. ［トークンを追加］ > ［Analytics］をクリックします。

      2. ［新しい Analytics トークン］サイド パネルで、次の情報を指定します。

        フィールドまたはオプション 説明
        説明

        次のような有用な情報を提供する説明を入力します。

        • トークンの目的
        • トークンの使用場所 - 例えば、Analyticsスクリプトの名前と場所、ロボットのタスクの名前と場所など。
        トークンの有効期限
        • 有効 指定した日数後にトークンの有効期限が切れます
        • 無効 トークンの有効期限はありません

        メモ

        あなたの組織には、トークンを一定期間後に失効させるセキュリティポリシーがあるかもしれません。有効期限付きのトークンを作成することは良い習慣です。Diligent One では、有効期限の前に自動でメール通知が送られます。
        有効期限が切れるまでの日数 トークンの有効期限が切れるまでの日数を指定します (1～365)。
        パスワード Diligent One アカウントのパスワードを入力します。

      3. ［トークンを生成］をクリックします。

      4. ［コピー ］をクリックしてトークンをコピーします。

        ヒント

        トークンが含まれているこのサイド パネルは、トークンを貼り付けるまで閉じないでください。

  3. 使用しているパスワード定義方法に応じて次のいずれかを実行します。

    • PASSWORDアナリティクスタグACLロボットのタスクデザイナーで、コピーしたトークンをパスワーACL robotドパラメーターフィールドに貼り付けます。

    • PASSWORD コマンドAnalytics で、コピーしたトークンを、スクリプト実行中に表示されるパスワードの確認に貼り付けます。

    • SET PASSWORD コマンドAnalytics で、スクリプトの SET PASSWORD コマンド構文内の適切な位置にコピーしたトークンを貼り付けます。

  4. Launchpad で、トークンが含まれているダイアログボックスまたはサイド パネルを閉じます。

    新しいトークンを作成した場合は、部分的にマスクされたバージョンのトークンが、トークンのリストに追加されます。

    詳細については、HighBond アクセストークンの作成と管理を参照してください。HighBond access tokens