メインコンテンツまでスキップ

ReportingDataAPI

このガイドは、OpenLM Reporting へのアクセスが必要な外部およびクライアント側のインテグレーター向けです。ReportingDataAPI は認証に OAuth 2.0 を使用します。

概要

ReportingDataAPI からデータを読み取るには、OpenLM Identity Server で認証し、短期間有効な JWT アクセストークンを受け取り、そのトークンをすべての API リクエストで Bearer 認証情報として送信します。

フローは次の 3 ステップです。

1. Client ID + Client Secret ──▶ 2. POST /connect/token ──▶ 3. Call the API
(issued to your service) (Identity Server)

これはサーバー間 (server-to-server) フローです。ユーザーログインやブラウザーのリダイレクトはありません。アプリケーションは自分自身として認証します。

前提条件

認証して API を呼び出すには、次のものが必要です。

必要なもの値または取得元
Client IDお客様ごとに発行されるクライアント。
Client Secretクライアントとともに発行されます。秘密として扱い、決してコミットしないでください。
Identity Server ベース URL {IDENTITY_URL}https://cloud-us.openlm.com/identity(prod-us)または https://cloud-eu.openlm.com/identity(prod-eu)。
ベース URL {BASE_URL}https://cloud-us.openlm.com(prod-us)または https://cloud-eu.openlm.com(prod-eu)。
スコープopenlm.reporting-data-api-service.scope
ReportingDataAPI ベース URL {API_BASE_URL}{BASE_URL}/api/reportingdataapi
注意

このクライアントは client_credentials グラントをサポートします。発行されるアクセストークンは JWT で、有効期間は 3,600 秒(1 時間)です。このクライアントが属するお客様は Client ID(末尾の GUID)にエンコードされ、トークンの customer_name クレームとして公開されます。

ステップ 1 — クライアント認証情報を生成する

インテグレーションは Client ID で識別され、Client Secret で認証されます。これらの値は、ログイン後に OpenLM Identity ページで自分で生成します。お客様ごとに個別のクライアントがプロビジョニングされるため、生成される Client ID にはお客様 ID が含まれます。

Identity ページにログインする

OpenLM アカウントでサインインした後、ブラウザーで OpenLM Identity ページを開きます。

  • Prod-us: https://cloud-us.openlm.com/identity
  • Prod-eu: https://cloud-eu.openlm.com/identity

新しいクライアントを生成する

Identity ページで、クライアントまたは API アクセスのセクションに移動し、ReportingDataAPI 用の新しいクライアントを作成します。

Client ID と Client Secret をコピーする

クライアントを生成したら、両方の値をすぐにコピーするか、JSON をダウンロードします。

  • Client ID。
  • Client Secret — 作成時にのみ表示されるため、ここで保存してください。
警告

Client Secret は生成時に一度だけ表示されます。紛失した場合は、新しいクライアントを生成してください。シークレットはシークレットマネージャーまたは環境変数に保存し、決してソースにハードコードしたりリポジトリにコミットしたりしないでください。

export OPENLM_CLIENT_ID="<your-client-id>"
export OPENLM_CLIENT_SECRET="<your-client-secret>"
export OPENLM_IDENTITY_URL="https://<your-base-url>/identity"

ステップ 2 — トークンエンドポイントを確認する(ディスカバリー)

Identity Server は OpenID Connect ディスカバリードキュメントを公開しています。正確なトークンエンドポイントは、次の場所で確認できます。

GET {IDENTITY_URL}/.well-known/openid-configuration

該当するフィールドは token_endpoint で、次のように解決されます。

{IDENTITY_URL}/connect/token

ディスカバリーは一度だけ実行すれば十分です。トークンエンドポイントのパス(/connect/token)は安定しています。

ステップ 3 — アクセストークンをリクエストする

grant_type=client_credentials を指定して、トークンエンドポイントに POST を送信します。

リクエスト(curl)

curl -X POST "$OPENLM_IDENTITY_URL/connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=$OPENLM_CLIENT_ID" \
-d "client_secret=$OPENLM_CLIENT_SECRET" \
-d "scope=openlm.reporting-data-api-service.scope"

レスポンス

{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openlm.reporting-data-api-service.scope"
}

access_token を取り出します。これは JWT です。デコードして(例: jwt.io で)、customer_namenameemailrole などのクレームを確認できます。

ステップ 4 — トークンを使用して ReportingDataAPI を呼び出す

トークンをすべてのリクエストで Authorization: Bearer ヘッダーとして送信します。サポートされるスキーマの完全な一覧については、このページ後半の「エンドポイントと GraphQL クエリ」セクションを参照してください。

REST の例

curl -X GET "{API_BASE_URL}/<endpoint>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Accept: application/json"

GraphQL の例

curl -X POST "{API_BASE_URL}/graphql" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "query": "{ licenseUsage(first: 25) { totalCount pageInfo { hasNextPage endCursor } nodes { user_name feature_name vendor start_time_utc } } }" }'

トークンの有効期間と更新

  • アクセストークンの有効期間は 3,600 秒(1 時間)です(expires_in: 3600)。
  • client_credentials フローはリフレッシュトークンを発行しません。トークンの有効期限が近づいたら、ステップ 3 を繰り返して新しいトークンを取得します。
  • ベストプラクティス: トークンをメモリにキャッシュし、expires_in の値を追跡して、API 呼び出しのたびにではなく有効期限の数秒前に再取得します。

トラブルシューティング

症状考えられる原因対処
400 invalid_clientClient ID または Secret が間違っているか、シークレットが別の環境のものです。認証情報がその環境の Identity Server と一致していることを確認します。
400 invalid_scopeスコープのスペルが間違っています。正確に openlm.reporting-data-api-service.scope を使用します。
API からの 401 Unauthorizedトークンが欠落または期限切れか、オーディエンスが間違っています。トークンを再取得し、Authorization: Bearer <token> ヘッダーがあることを確認します。
403 Forbiddenトークンは有効ですが、そのテナントまたはリソースに対する権限がありません。customer_name クレームまたは X-Customer-Name ヘッダーを確認します。
トークンが機能した後、約 1 時間で失敗する。トークンが期限切れになりました。新しいトークンを取得します(ステップ 3)。

リファレンス — Identity 設定(正式な値)

設定
クライアントシークレットの要否必須
スコープopenlm.reporting-data-api-service.scope
アクセストークンの種類JWT
アクセストークンの有効期間3,600 秒(1 時間)
トークンクレームname, email, customer_name, role
トークンエンドポイント{IDENTITY_URL}/connect/token
ディスカバリー{IDENTITY_URL}/.well-known/openid-configuration

エンドポイントと GraphQL クエリ

認証(トークンの取得)については、このページ前半の「概要」で説明しています。以下のすべてのリクエストには、有効な Authorization: Bearer <token> ヘッダーが必要です。

ReportingDataAPI は GraphQL API です。すべてのデータは単一のエンドポイント経由で読み取ります。

エンドポイントメソッド用途
{API_BASE_URL}/graphqlPOSTすべてのデータクエリ(GET ではブラウザー内 GraphQL エクスプローラー)。
{API_BASE_URL}/healthGETヘルスチェック。

フィールドの命名: スキーマは camelCase です(licenseUsagepageInfototalCountorderBy など)。groupBy および orderBy の引数値は snake_case の生の列名です(例: "feature_name")。

次の表は、これらのクエリ全体で開発者が使用するパラメーターの型の概要です。

パラメーター説明
firstInt(カーソルページング)先頭から取得するレコード数。例: first: 25
afterString(カーソルページング)前回のレスポンスのカーソル文字列。その後の次ページを取得します。
last / beforeInt / String(カーソルページング)考え方は同じですが、末尾から逆方向にページングします。
skipInt(オフセットページング)読み取り前にスキップするレコード数。
takeInt(オフセットページング)スキップ後に読み取るレコード数。
searchTermString(フィルターリスト)ドロップダウンの値を絞り込む任意のテキスト。空にするとすべての一意な値を取得します。
limitInt(ウィジェット専用)ウィジェットが返す行数。各クエリの注記を参照してください。
where(フィルターオブジェクト)結果の任意のフィールドに対する任意のフィルター(サーバーが自動生成)。
order(ソートオブジェクト)結果の任意のフィールドに対する任意のソート(サーバーが自動生成)。
注意

利用可能なクエリはデプロイメントモードによって異なります。(オンプレミスのみ)と記載されたクエリはセルフホスト版にのみ存在します。(クラウドのみ)と記載されたクエリはクラウド版にのみ存在します。それ以外はすべて両方に存在します。

メインレポートクエリ

これらはページングされたデータを返します。カーソルページングのパラメーター firstafterlastbefore を使用します。また、任意のフィールドに対する where(フィルター)と order(ソート)も受け付けます。

クエリパラメーター説明
licenseUsagefirst, after, last, before, where, orderライセンス使用レコード。
licenseDenialsfirst, after, last, before, where, orderライセンス拒否レコード。
sessionDetailsfirst, after, last, before, where, orderアプリケーション/セッションレコード。
projectDatafirst, after, last, before, where, orderプロジェクトレコード。
devices(オンプレミスのみ)first, after, last, before, where, orderテナントスコープのデバイスレコード。

使い方: 例えば licenseUsage(first: 25) から始めます。レスポンスには pageInfo.hasNextPageendCursor が含まれます。そのカーソルを after として渡すと次のページを取得できます: licenseUsage(first: 25, after: "<endCursor>")totalCount は全レコード数を返します。

カウントクエリ

これらは単一の数値を返し、パラメーターを取りません。

クエリ戻り値意味
licenseUsageActiveLicenseCountInt現在アクティブなライセンスの数。
licenseUsageHostRunningCountInt現在実行中のホストの数。
licenseDenialsDenialCountInLast24HoursInt過去 24 時間の拒否数。
licenseDenialsNewAlertsCountIn24HoursInt過去 24 時間における一意な新規拒否アラート数。

使い方: 例えば { licenseUsageActiveLicenseCount } のように直接呼び出します。

フィルター値ルックアップクエリ

これらは、1 つのフィールドについて重複のないソート済みの値をページング形式で返し、フィルターのドロップダウンを構築するのに使用します。いずれも任意の searchTerm と、オフセットページングのパラメーター skiptake を取ります。

すべてに共通のパラメーター: searchTerm(String、任意)、skip(Int)、take(Int)。

License Usage: licenseUsageLicenseTypeFilterValues, licenseUsageVersionFilterValues, licenseUsageUserNameFilterValues, licenseUsageWorkstationFilterValues, licenseUsageVendorFilterValues, licenseUsageFeaturePackageFilterValues, licenseUsageFeatureProductFilterValues, licenseUsageFeaturePackageItemFilterValues, licenseUsageIsTokenBasedFilterValues

License Denials: licenseDenialsUserNameFilterValues, licenseDenialsWorkstationFilterValues, licenseDenialsMinorErrorFilterValues, licenseDenialsMajorErrorFilterValues, licenseDenialsErrorTextFilterValues, licenseDenialsFeatureNameFilterValues, licenseDenialsStatusFilterValues, licenseDenialsGroupIdFilterValues, licenseDenialsGroupNameFilterValues, licenseDenialsCategoryFilterValues, licenseDenialsVendorFilterValues, licenseDenialsFeatureVersionFilterValues, licenseDenialsLicenseTypeFilterValues, licenseDenialsAdditionalKeyFilterValues, licenseDenialsHostnameFilterValues, licenseDenialsLicenseServerFilterValues

Session Details: sessionDetailsUserFilterValues, sessionDetailsWorkstationFilterValues, sessionDetailsIdleTimeFilterValues, sessionDetailsSessionEndTimeHolidaysFilterValues, sessionDetailsSessionEndTimeWeekdaysFilterValues, sessionDetailsSessionFilterValues, sessionDetailsProcessFilterValues, sessionDetailsDependencyFilterValues, sessionDetailsCustomerFilterValues, sessionDetailsReasonFilterValues, sessionDetailsAgentStatusFilterValues, sessionDetailsVersionFilterValues

注意

Session Details では、searchTerm の型が異なります。sessionDetailsIdleTimeFilterValuessessionDetailsSessionFilterValues は Float の searchTerm を取ります。sessionDetailsAgentStatusFilterValues は Int の searchTerm を取ります。2 つの SessionEndTime クエリは DateTime の searchTerm を取ります。その他は String の searchTerm を取ります。

Touchpoint Details: touchpointDetailsUsernameFilterValues(String)、touchpointDetailsWorkstationFilterValues(String)、touchpointDetailsEventDateTimeFilterValues(DateTime の searchTerm

Dongle Monitoring: dongleMonitoringDeviceNameFilterValuesdongleMonitoringDeviceDescriptionFilterValuesdongleMonitoringManufacturerFilterValuesdongleMonitoringUserNameFilterValuesdongleMonitoringHostNameFilterValuesdongleMonitoringBlacklistedFilterValues は String の searchTerm を取ります。dongleMonitoringAgentStatusFilterValues は Int の searchTerm を取ります。

Project Data: projectDataProjectNameFilterValuesprojectDataUserNameFilterValuesprojectDataPriorityFilterValuesprojectDataSourceFilterValues(すべて String の searchTerm

デバイスフィルター(オンプレミスのみ): deviceNameFilterValuesdeviceManufacturersFilterValuesdeviceHostNameFilterValuesdeviceUserNameFilterValues

注意

これらは searchTerm(String)と skiptake を取ります。さらに、deviceHostNameFilterValuesdeviceUserNameFilterValues は、結果を 1 つのデバイスに限定する任意の deviceId(String)を受け付けます。

使い方: licenseUsageVendorFilterValues(searchTerm: "auto", take: 20) は "auto" を含む一意なベンダーを最大 20 件返します。すべての値を一覧するには searchTerm を省略します。

ダッシュボードウィジェットクエリ

これらは(ページングされていない)単純なリストを返します。主要なパラメーターは limit です。

limit パラメーターの説明:

  • Top-N ウィジェット: limit は 5 または 10 のみに制限されます。それ以外の値(または省略時)は 10 になります。つまり limit: 5 → 5 行、それ以外 → 10 行。
  • 全リストウィジェット(activeUsersReportlicenseServerStatushostAvailability): limit は 1〜100 を受け付けます。範囲外または省略時は安全上限として 100 になります。
クエリパラメーター説明(戻り値/並び順)
topDeniedFeatureslimit: Int(5/10)拒否が最も多い機能。多い順。
topDeniedUserslimit: Int(5/10)拒否が最も多いユーザー。多い順。
topMostUsedFeatureslimit: Int(5/10)最も使用された機能。使用量が多い順。
topLeastUsedFeatureslimit: Int(5/10)最も使用されていない機能。使用量が少ない順。
topLongestSessionslimit: Int(5/10)最も長いセッション。長い順。
topIdleSessionslimit: Int(5/10)最もアイドル時間が長いセッション。アイドル時間が長い順。
topProductNameslimit: Int(5/10)使用量上位の製品。
topVendorNameslimit: Int(5/10)使用量上位のベンダー。
topMostActiveUserslimit: Int(5/10)最もアクティブなユーザー(1 セッション以上のユーザーのみ)。
topLeastActiveUserslimit: Int(5/10)最もアクティブでないユーザー(1 セッション以上のユーザーのみ)。
activeUsersReportlimit: Int(1〜100、デフォルト 100)現在アクティブなセッション。
licenseServerStatuslimit: Int(1〜100、デフォルト 100)ライセンスサーバーのステータス一覧。
hostAvailabilitylimit: Int(1〜100、デフォルト 100)ホストの可用性一覧。

使い方: topDeniedFeatures(limit: 5) は上位 5 件を返します。activeUsersReport(limit: 50) は最大 50 件のアクティブセッションを返します。

クエリのフィールド一覧

メインレポートクエリ — フィールド

nodes { } 内で次のフィールドを選択します。

licenseUsage

usage_id (String), borrowed (Int), country (String), department (String), duration (Float), email (String), end_time_utc (DateTime), feature_name (String), first_name (String), group_name (String), host_id (String), host_name (String), idle_time (Float), is_token_based (String), last_name (String), lic_inv_additional_key (String), lic_inv_type (String), lic_inv_vendor (String), lic_inv_version (String), license_id (String), mobile_phone (String), num_of_licenses (Int), package_id (String), package_name (String), product_name (String), project_name (String), quantity (Int), region (String), remote_ip (String), server_id (String), server_name (String), software_name (String), source (String), start_date_utc (DateTime), start_time_utc (DateTime), user_id (String), user_name (String)

licenseDenials

denial_id (String), additional_key (String), category (String), date_utc (DateTime), denial_category (String), denial_date (DateTime), denial_hour_in_day_utc (Int), denial_hour_utc (DateTime), denial_month_utc (DateTime), denial_timestamp (DateTime), denial_type (String), denial_week_utc (DateTime), department (String), error_message (String), feature_name (String), grp_id (String), grp_is_computers_group (Int), grp_is_user_group (Int), grp_name (String), grp_timestamp (DateTime), host_name (String), host_port (String), license_id (String), license_type (String), licsrv_description (String), licsrv_istokenenabled (String), licsrv_licmanager (String), licsrv_timestamp (DateTime), licsrv_timezone (String), major_err (String), minor_err (String), num_of_licenses (Int), product_name (String), project_id (String), project_name (String), region (String), series_no (String), server_id (String), status (String), transaction_id (String), ts_ms (DateTime), user_country (String), user_description (String), user_display_name (String), user_email (String), user_first_name (String), user_id (String), user_is_valid (String), user_last_name (String), user_lower_user_name (String), user_mobile_phone (String), user_name (String), user_office (String), user_phone_number (String), user_timestamp (DateTime), vendor (String), version (String), workstation (String)

sessionDetails

session_id (String), agent_status (Int), customer_id (String), dll_name (String), host_name (String), monitoring_id (String), process_id (String), process_name (String), session_duration_in_min (Float), session_end_time (DateTime), session_start_time (DateTime), shutdown_reason (String), total_idle_time_in_min (Float), transaction_id (String), user_id (String), user_name (String), version (String)

touchpointDetails

id (String), customer_id (String), event_date_time (DateTime), event_type (Int), event_type_desc (String), found_url (String), page_title (String), row_number (Long), touchpoint_event_source (String), ts_ms (DateTime), user_id (String), user_name (String), website_type (String), workstation (String), local_host (String), main_domain (String), sub_domain (String)

dongleMonitoring

monitoring_id (String), agent_status (Int), blacklisted_when_connected_or_disconnected (String), customer_id (String), device_connected_date_time (DateTime), device_description (String), device_disconnected_date_time (DateTime), device_identifier (String), device_name (String), host_name (String), last_update_date_time (DateTime), manufacturer (String), row_number (Long), serial_number (String), user_name (String), vendor (String), user_id (String)

projectData

project_id (String), action (Int), end_date_utc (DateTime), group_id (String), group_name (String), is_enabled (String), percent_done (Float), priority (String), project_name (String), row_number (Long), source (String), start_date_utc (DateTime), ts_ms (DateTime), user_name (String), priority_text (String)

devices(オンプレミスのみ)

TenantId (String), UserId (String), DeviceIdentifier (String), DeviceName (String), DeviceDescription (String), Manufacturer (String), DeviceConnectedDateTime (DateTime), LastUpdateDateTime (DateTime), DeviceDisconnectedDateTime (DateTime), UserName (String), HostName (String), BlacklistedWhenConnectedOrDisconnected (Boolean), SerialNumber (String), AgentStatus (AgentStatus enum), Vendor (String)

例:

{
licenseUsage(first: 25) {
totalCount
pageInfo { hasNextPage endCursor }
nodes {
user_name
feature_name
vendor
start_time_utc
}
}
}

カウントクエリ — フィールドなし

licenseUsageActiveLicenseCountlicenseUsageHostRunningCountlicenseDenialsDenialCountInLast24HourslicenseDenialsNewAlertsCountIn24Hours はそれぞれ単一の Int を返します。クエリ名を直接リクエストします。

{ licenseUsageActiveLicenseCount }

フィルター値クエリ — クエリごとの値の型

これらには選択するフィールド名がありません。items が生の値を直接返します。各値の型は次のとおりです。

  • String 値: すべての License Usage、License Denials、Project Data、Device、Touchpoint のユーザー名/ワークステーションフィルター。加えて、Session Details のユーザー/ワークステーション/プロセス/依存関係/顧客/理由/バージョンフィルター、Dongle のデバイス名/説明/製造元/ユーザー名/ホスト名/ブラックリストフィルター。
  • Float 値: sessionDetailsIdleTimeFilterValuessessionDetailsSessionFilterValues
  • Int 値: sessionDetailsAgentStatusFilterValuesdongleMonitoringAgentStatusFilterValues
  • DateTime 値: sessionDetailsSessionEndTimeHolidaysFilterValuessessionDetailsSessionEndTimeWeekdaysFilterValues

例:

{
licenseUsageVendorFilterValues(searchTerm: "", take: 20) {
totalCount
pageInfo { hasNextPage }
items
}
}

ウィジェットクエリ — フィールド(Cloud のみ)

フィールドを直接選択します。

topDeniedFeatures

feature_name (String), vendor (String), product_name (String), license_type (String), denial_type (String), denial_category (String), denial_count (Long), last_denial_date (DateTime)

topDeniedUsers

user_id (String), user_name (String), department (String), email (String), denial_count (Long), unique_denied_features (Long), last_denial_date (DateTime)

topMostUsedFeatures / topLeastUsedFeatures

feature_name (String), software_name (String), vendor (String), license_type (String), package_id (Int), total_duration_days (Float), unique_users (Long), last_used_utc (DateTime)

topLongestSessions

usage_id (Int), feature_name (String), software_name (String), vendor (String), package_id (Int), server_name (String), user_id (String), user_name (String), first_name (String), last_name (String), department (String), group_name (String), start_time_utc (DateTime), end_time_utc (DateTime), date (DateTime), duration_days (Float), idle_time_hours (Float), is_active (Boolean)

topIdleSessions

usage_id (Int), feature_name (String), software_name (String), vendor (String), package_id (Int), server_name (String), user_id (String), user_name (String), first_name (String), last_name (String), department (String), group_name (String), start_time_utc (DateTime), end_time_utc (DateTime), duration_days (Float), idle_time_hours (Float)

topProductNames

product_name (String), vendor (String), session_count (Long), total_duration_days (Float), unique_users (Long), unique_features (Long)

topVendorNames

vendor (String), package_id (Int), session_count (Long), total_duration_days (Float), unique_users (Long), unique_features (Long), unique_products (Long)

topMostActiveUsers / topLeastActiveUsers

user_id (String), package_id (Int), user_name (String), first_name (String), last_name (String), department (String), email (String), mobile_phone (String), group_name (String), session_count (Long), total_duration_days (Float), total_idle_time_hours (Float), unique_features (Long), last_seen_utc (DateTime)

activeUsersReport

usage_id (Int), user_id (String), user_name (String), group_name (String), feature_name (String), software_name (String), server_name (String), host_id (String), num_of_licenses (Int), borrowed (Int), idle_time_hours (Float), start_time_utc (DateTime), date (DateTime), running_days (Long), running_hours (Long), running_minutes (Long), running_seconds (Long), borrowed_text (String), session_length_category (String)

licenseServerStatus

transaction_id (String), server_id (Int), server_name (String), license_manager_type (String), host_name (String), server_port (Int), host_status (String), server_status (String), update_date_utc (DateTime), ts_ms (String), ts_ms_converted (DateTime)

hostAvailability

host_name (String), server_port (Int), host_status (String), server_name (String), vendor (String), license_manager_type (String), last_seen_utc (DateTime)

例:

{
topDeniedFeatures(limit: 5) {
feature_name
vendor
denial_count
last_denial_date
}
}