REST APIおよびPython APIのドキュメント

このページでは、Requirements PortalのREST APIのリファレンスを提供します。REST APIを使用すると、Requirements Portalのデータを取得・変更したり、Requirements Portalにデータを書き戻して情報を更新したりできます。また、他のアプリケーションとの接続・統合も可能になります。

トークンを使用したRequirements PortalのREST APIへのアクセス

Requirements PortalのREST APIにアクセスするには、Settings – User Tokensページでトークンを生成します （右上の アイコンをクリックし、表示されるメニューからSettingsを選択して、左側のペインのリストからUser Tokensを選択するとアクセスできます）。このページには、お使いの環境固有のAPI addressが表示されます。このアドレスは、API呼び出しに必要です。

Settings – User Tokensページの右下にある+ アイコンをクリックして、新しいトークンを生成します。各トークンの有効期間は3 monthsで、有効期限が切れたら再生成する必要があります。

access_tokenを使用してAPIを利用するには、アプリケーションタイプを「JSON」とし、HTTPリクエストのAuthorizationヘッダーに「Bearer ...」形式でトークンを追加する必要があります。

curl --location 'http://deployment_name/rest/requirements/versions/search/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer hO2lwhLZsYOgXPNVI' \
--data '{
    "size": 10,
    "query_filters": {
        "object_id": 93
    }
}'

また、requestsを使用する場合は、次のようにアクセストークンを送信できます。

access_token = 'Generated_Access_token'
api_url = 'Api_Address'

# workspace id and component type

workspace_id = 1
component_type_name = "CompA"

# Define headers with the access token
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',  # Adjust content type as needed
}

# Make a GET request (you can use other HTTP methods like POST, PUT, etc.)
component_types_workspace = requests.get(api_url + "components/types/?workspace="+str(workspace_id), headers=headers)

Python APIドキュメント

Python API を使用すると、Pythonコードでお使いの環境のオブジェクトにアクセスし、更新できます。

必要なPython APIパッケージをpipでインストールします。

pip install valispace

PythonスクリプトでAPIモジュールをインポートします。

import valispace

次のように初期化します。

valispace = valispace.API()

APIの機能や関数の詳細は、 こちらをご覧ください。Python APIパッケージはMITライセンスで提供されているため、誰でもGitHubリポジトリをクローンしてコードに貢献できます。

エンドポイント

ユーザーはSwaggerページでエンドポイントにアクセスできます。このページにアクセスするには、Settings – User Tokensページに記載されているAPI URLの末尾にswagger/を追加します。このページには、既存のすべてのエンドポイントを含むDjango Swaggerが表示されます。

GET、POST、PUT、PATCH、DELETEのメソッドがあります。

Requirements Portalの各オブジェクトには固有のIDがあります。このIDを使用して、オブジェクトを検索し、その情報を取得できます。オブジェクトIDは、Requirements Portalで直接確認するか、Requirements Portalでオブジェクトをクリックした際のURLで確認できます。

例えば、SwaggerからGET関数を使用して要件の履歴情報を取得する場合、次のエンドポイントを使用して要件履歴の詳細を取得できます。

GET /rest/requirements/{requirement-id}/history/

GETを使用した要件履歴情報の取得

同様に、これらのメソッドを使用して、ブロック、タグ、valis、textvalis、要件、仕様、検証方法など、さまざまなオブジェクトを取得・更新・投稿できます。エンドポイントはSwaggerページで検索できます。

プロジェクト別のオブジェクトのフィルタリング

認証に加えて、GETメソッドを使用して、環境内のValisや要件などのオブジェクトを取得できます。特定のプロジェクトに基づいて結果を絞り込む必要がある場合は、エンドポイントが対応するように設定されていれば、フィルタリング機能を利用できます。例えば、プロジェクト24に関連する要件を取得するには、次のGETリクエストを使用します。

GET /rest/requirements/?project=24

理解を深めるために、以下の動画でこの機能を実演しています。

組み込み関数

Requirements Portalでは、ユーザーがテキストフィールドに入力すると、そのテキストはバックエンドにHTML形式で保存されます。HTML形式では、書式設定とvalisやその他のオブジェクトへの参照が保持されます。そのため、要件情報を取得すると、インポートするデータにHTMLテキストが含まれる場合があります。これに対応するため、HTMLフィールドをプレーンテキストに変換する関数と、HTMLの書式を保持しながらvalisをテキストに変換する関数を実装しています。これらの関数はclean_textとclean_htmlです。

clean_text関数

clean_text関数は、フィールド内のすべてのHTML書式とオブジェクト参照をテキストに変換します。ただし、この場合は書式設定も失われます。例えば、リスト、表、色が含まれていても、それらの書式は失われます。以下のように使用できます。

ここでは、プロジェクト24でフィルタリングし、フィールドのテキストと根拠をプレーンテキストで取得するよう指定しています。この操作の出力は次のようになります。

clean_text関数を使用した後の要件

clean_html関数

clean_html関数は、テキストの書式設定を保持しつつ、valisなどの参照やオブジェクトをテキストに変換します。テキストにリスト、背景色、表などの書式設定が含まれている場合、それらの情報は保持されます。

clean_html関数を使用した後の要件

よくある質問

適切なエンドポイントを見つけるには？

似た名前のエンドポイントが多数あると、どれを使うべきか迷うことがあります。特定のエンドポイントについて不明な点がある場合は、Altiumサポートページからお問い合わせください。また、ブラウザーの「ネットワーク」機能を利用して、ソフトウェアのフロントエンドで操作を行った際に、どのエンドポイントが呼び出されるかを確認することもできます。

例として、ブロックを作成する操作を考えてみましょう。この場合、関連するエンドポイントは「/rest/components」への「POST」リクエストとして特定できます。この情報は、操作中のネットワーク通信を調べることで簡単に確認できます。以下の短い動画で、この方法を簡潔に実演しています。