SystemLinkのHTTP APIでAPI Keyを作成・使用する方法

SystemLink HTTP APIは、Basic認証の代わりにAPIキーを使用して実行できます。これは、認証サーバとの過剰な通信を防ぐためによく使用されます。この記事では、APIキーの作成方法と使用方法について説明します。

SystemLink GUIの「アクセス権」ページには、役割、ワークスペース、ユーザがオプションとしてありますが、これらは階層構造になっています。APIには、さまざまな名前を持つ多数のオブジェクトが含まれています。以下に、それらを簡単にまとめます。

GUI要素：

• ワークスペースは、管理可能なアイテム（ファイル、タグ、システムなど）のサブセットであり、明確な名前（例：デフォルト）が付けられています。
• ユーザは、1つ以上のワークスペースで1つ以上の役割が割り当てられたログインアカウント（またはアカウントの論理グループ）です。
• 役割は、「Data Maintainer」などの明確な名前を持つ基本権限の集合です。
  
• 権限とは割り当てられたワークスペース内で、そのワークスペースでユーザに割り当てられた役割に基づいてユーザが実行できるアトミックなアクションのことです（例：ファイルのアップロード、ソフトウェアのインストール）。

APIクラス：

• API キーは、ユーザに関連付けられたポリシーのコレクションを、わかりやすい名前（例：Super User Access ）で記述します。
  
• ポリシー(policy)は、権限の完全なセットを構築するstatementsのコレクションを、わかりやすい名前（例：Super User)で記述します。
  
• ステートメントは、関連付けられたワークスペース(workspace)、リソースリスト(resource)、アクション（actions)のコレクションのことです（例：ファイル管理）。
  
• アクション（actions)は、GUIの役割権限リストに表示されるようなアトミックな権限（例：ファイルのクエリ、ファイルの削除、ファイルのダウンロード、メタデータの更新）を記述します。

APIキーは、前述のAPIクラスの包含関係に基づいたボトムアップアプローチに従いて作成する必要があります。

以下の手順を実行する前に、Auth Service Swagger UIページへのアクセス権と、以下の HTTPメソッドを実行するための適切な権限があることを確認してください。なお、Auth Service Swagger UIページは<server_url>/niapisに移動し、Select a definitionドロップダウンメニューから「Auth Service」を選択してアクセスできます。

※注: デフォルトでは、管理者ユーザ（Admin)のみがAPIキーを作成できます。

1. Policyの作成 (POST /niauth/v1/policies)
2. API keyの作成 (POST /niauth/v1/keys)
3. API keyの使用方法

1. Policyの作成 (POST /niauth/v1/policies)

Policiesの作成は下図の通り、特定のnameに対してこのユーザーが使用可能なactions, アクセス可能なresource及びworkspaceを指定し、発行します。ここではnameで指定したuser1に対して0d92be8b-4772-4965-8f57-9e1644a03bf2というpolicy IDが作成されています。
 

• デモ用に「すべて」を意味するアスタリスク（*）ワイルドカードを使用していることに注意してください。つまり、このポリシーでは、すべてのワークスペースのすべてのリソースに対するすべてのアクションが許可されます。カスタムポリシーではより制限を厳しくすることもできますが、具体的なアクションとリソースを確認することは容易ではないです。推奨される方法はカスタムポリシーで使用できるアクションとリソースの例を含む GET /niauth/v1/policy-templates を使用することです。
• もう1つの方法は、ポリシーテンプレートに基づいてポリシーを作成することです。これを行うには、上記のリクエスト本文を変更し、「statements」プロパティを削除し、「templateId」と「workspace」の両方を最上位プロパティとして追加します。
• 1つのpolicy IDを複数のAPI keyの作成に使用する事ができます。Policyの内容について同じものを複数のクライアントに適応する場合、1つのAPI keyを複数のクライアントで使用する事ができます。クライアント事にアクセス可能なリソース、実行可能なコマンドを設定する場合、それぞれについてpolicyを作成する必要があります。
  
   

2. API keyの作成 (POST /niauth/v1/keys)

   作成したPolicy IDを使用して、API keyを作成します。ここではnameで指定したuser1に対してsecretとして表示されているAPI key = aOFkYvM8eaypigGpMUmxbHRn-NhjkPTOTmahQbWHYSが作成されました。API Keyの削除にはここで表示されているid = 15e4b028-ff7c-405f-9060-0ed22b5976daが必要となります。API keyはユーザーが意図的に削除もしくは有効期限の設定を行わない限り、失効しません。
   
   
    

   この手順を完了すると、APIキーが生成されます。ユーザのsecretを入力し、IDを記録しておいてください。後でAPIキーを更新または削除する必要がある場合は、APIキーIDが必要になります。

   次のセクションでは、LabVIEWプログラムでAPIキーのsecretを使用する例を示します。

3. API keyの使用方法

   SystemLink Serverから発行したAPI keyはx-ni-api-keyヘッダに含めることでBasic認証の代わりとして使用できます。例えば下記の様にPOST niauth/v1/keysを使用してAPI keyの一覧を出力すると、SystemLink Serverにシステムとして登録されている機材はAPI keyを保有している事が確認できます。
   
   
   
   

また、このAPIキーは様々なサービスに使用できます。例えば、この記事ではBasic認証（ユーザ名およびパスワード）を使用してTagの値を確認する方法を紹介しています。APIキーを作成すれば、ユーザ認証するため過剰なプロセスなし、リクエストが実行され、返答がより高速で取得できます。これはリクエストクエリが長い特に特に便利です。