--- title: API リファレンス description: OpenLM Platform の OpenLM LicOps のアドミッションエンドポイント、そのリクエストとレスポンスのフィールド、拒否理由、および LicOps を運用するための補助エンドポイント。 product: OpenLM Platform --- このページは、統合を作成するときや、手元にある LicOps のレスポンスの意味を知りたいときに参照してください。このセクションのほかのページでは、各リクエストを、それが使われるタスクの中で説明しています。 ## 各 LicOps ホストの API ブラウザー すべての LicOps デプロイは、実行中のビルドから生成されたインタラクティブなリファレンスを次のアドレスで提供しています。 ```text http://:8100/swagger ``` 使用しているビルドの正確なスキーマは、ここで確認してください。掲載されている項目の大半は Router の運用向けです。統合が呼び出すのは、以下のアドミッションエンドポイントです。 :::warning[ポート 8100 と 8101 へのアクセスを制限する] ポート `8100` と `8101` は管理用のインターフェイスです。管理用ネットワークとジョブを投入するホストからのアクセスだけを許可し、インターネットには公開しないでください。公開するのは、クライアントが使用するライセンスポートだけにします。[システム要件](https://www.openlm.com/documentation/ja/cloud/deployment-operations/licops/system-requirements)を参照してください。 ::: ## アドミッションエンドポイント ベースパス: `http://:8100/api/v1/admission-controller`。リクエストとレスポンスは JSON で、フィールド名は camelCase、`decision` などの値は文字列です。エンドポイントを次の表に示します。 | メソッド | パス | 成功時 | その他の応答 | | --- | --- | --- | --- | | `POST` | `/admit` | 判定を含む `200` | 無効なボディの場合、または同じセッション ID を異なるベンダー、フィーチャー、シート数で再利用した場合は `400`。コールドスタート中は `Retry-After` 付きの `503`。 | | `POST` | `/dispatch` | ライセンスサーバーを含む `200` | 無効なボディの場合は `400`。不明なセッションの場合は `404`。`ThrottleDeferred` と `Retry-After` 付きの `503`、または `NoCapacityAtDispatch` 付きの `503`。 | | `POST` | `/release` | 常に `200` | 無効なボディの場合は `400`。 | | `GET` | `/availability` | 常に `200` | なし | ### Admit リクエストのフィールドを次の表に示します。 | フィールド | 必須 | 説明 | | --- | --- | --- | | `sessionId` | はい | 自分で生成する ID で、通常は UUID です。1 つのジョブの 3 つのリクエストすべてで使用します。セッションが有効な間は、同じ ID で admit を繰り返すと最初の応答が返されます。拒否された admit は保存されません。 | | `vendor` | はい | プールのベンダーデーモン名。大文字と小文字の区別を含めて完全一致です。 | | `feature` | はい | プールのフィーチャー名。大文字と小文字の区別を含めて完全一致です。スペースはスペースのまま送信します。 | | `user` | いいえ | ジョブを投入したユーザー。記録され、アドミッションルールで使用できます。 | | `host` | いいえ | ジョブの投入元。記録され、アドミッションルールでは **client host** として使用できます。 | | `totalQuantity` | いいえ | 許可するシート数。`1` 以上で、既定値は `1` です。すべてのシートが 1 台のサーバーから割り当てられます。 | | `jobDetails` | いいえ | シートとともに記録されるジョブのコンテキスト: `clusterName`、`account`、`queue`、`jobName`、`declaredRuntimeSeconds`、および Kubernetes では `namespace` と `podName`。各フィールドは任意です。判定には影響しません。 | レスポンス: | フィールド | 説明 | | --- | --- | | `decision` | `Admit` または `Deny`。 | | `sessionId` | `Admit` の場合はセッション ID、`Deny` の場合は `null`。 | | `expiresAt` | `Admit` の場合、それまでにジョブが dispatch されないとシートが失効する時刻。 | | `reason` | `Deny` の場合、その理由。[拒否理由](#拒否理由) を参照してください。 | コールドスタート中の `503` には、`type`、`title`、`status`、`traceId` を含む problem document と、`Retry-After` ヘッダーが付きます。 ### 拒否理由 拒否理由、発生した状況、対処方法を次の表に示します。 | 理由 | 発生した状況 | 対処方法 | | --- | --- | --- | | `NoServerAvailable` | このベンダーとフィーチャーを提供する正常なサーバーがありません。 | まず `GET /api/v1/stats` と照らしてスペルを確認します。次に、プールのサーバーが停止していないかを確認します。 | | `NoCapacity` | サーバーには到達できますが、要求を満たす空きシートを持つサーバーがありません。 | ジョブをキューに入れ、後で再試行します。 | | `ConstraintBlocked` | サーバーに空きシートはありますが、すべてのサーバーが予約による上限に達しているか、現在の期間中ブロックされています。 | 上限の範囲内でシートが空くのを待つか、予約を変更します。[スケジュールでシート数を制限する](https://www.openlm.com/documentation/ja/cloud/deployment-operations/licops/reservations) を参照してください。 | | `PolicyDenied` | **Deny the request** が設定されたアドミッションルールに一致しました。 | 意図された動作です。**LicOps Configuration** のルールを確認してください。 | | `StaleSnapshot` | LicOps が OpenLM Platform から最新の数値を受け取っていないため、自身のカウントを信頼していません。 | OpenLM Platform との同期を復旧します。それまでは再試行しても解決しません。[トラブルシューティング](https://www.openlm.com/documentation/ja/cloud/deployment-operations/licops/troubleshooting#licops-が-openlm-platform-と同期しないのはなぜですか) を参照してください。 | | `ContentionExhausted` | 現在は返されません。 | 対処は不要です。古いクライアントとの互換性のためにこの値が残されています。 | ### Dispatch リクエストのフィールドを次の表に示します。 | フィールド | 必須 | 説明 | | --- | --- | --- | | `sessionId` | はい | admit で送信した ID。 | | `executionNodeIp` | はい | ジョブを実行するノードの IP アドレス。チェックアウトのルーティングを使う場合、LicOps はこれを使ってノードのチェックアウトをこのセッションに対応付けます。 | | `jobId` | いいえ | スケジューラーのジョブ ID。記録されます。 | | `jobDetails` | いいえ | admit と同じです。ここで指定した値は、admit の値をフィールドごとに置き換えます。省略すると admit の値が保持されます。 | レスポンス: | フィールド | 説明 | | --- | --- | | `hostName`、`port` | チェックアウト先のライセンスサーバー。3 サーバー冗長構成のライセンスサーバーの場合は、その 1 台目のマシン。 | | `licenseFile` | `LM_LICENSE_FILE` に使用する値で、`port@host` の形式です。3 サーバー冗長構成のライセンスサーバーの場合は、3 台すべてのマシンをカンマ区切りで示します。返されたとおりにそのまま使用してください。 | | `fallbackTargets` | プール内のその他の正常なサーバー。それぞれに `hostName`、`port`、`licenseFile` があります。 | `404` のボディは空で、セッションが存在しないか、すでに終了していることを示します。`503` のボディはプレーンテキストで、Throttle ルールがチェックアウトのペースを調整している場合は `ThrottleDeferred`、セッションのサーバーに障害が発生し、プール内のほかのサーバーに空きシートがない場合は `NoCapacityAtDispatch` です。`ThrottleDeferred` の場合、シートは保持されたままです。`Retry-After` の時間だけ待ってから、もう一度 dispatch します。`NoCapacityAtDispatch` の場合、LicOps はセッションを解放済みで、`Retry-After` も送信しません。新しいセッション ID でもう一度 admit します。 ### Release リクエストに指定するのは `sessionId` だけです。レスポンスのステータスは常に `200` で、`state` は次のいずれかです。 | 状態 | 意味 | | --- | --- | | `Released` | このリクエストでシートが返却されました。 | | `AlreadyClosed` | セッションはすでに終了しています。対処は不要です。 | | `NotFound` | そのようなセッションは存在しません。対処は不要です。 | ### Availability `GET /availability` は、LicOps が把握しているすべてのプールと、その背後にあるすべてのサーバー (停止中のサーバーを含む) を、アドミッション自体が使用する数値とともに返します。何も変更しません。 | フィールド | 説明 | | --- | --- | | `lastPlatformSyncTime`、`lastReconcileTime` | LicOps が最後に OpenLM Platform から数値を受け取った時刻と、最後にその数値でカウントを補正した時刻。 | | `coldStart` | LicOps が最初の数値を受け取るまでは `true`。その間、admit は `503` を返します。 | | `staleForAdmission` | 数値が古すぎて信頼できない場合は `true`。その間、admit は `StaleSnapshot` で拒否します。 | | `pools[]` | プールごとに 1 エントリ。`vendor`、`feature`、アドミッションが使用できるサーバー全体の合計値 `total`、`used`、`reserved`、`free`、および `largestAdmittableRequest` (現時点で 1 つのリクエストが取得できる最大シート数) を含みます。 | | `pools[].servers[]` | サーバーごとに 1 エントリ。`isHealthy`、シート数、`constraints` を含みます。 | | `pools[].servers[].constraints[]` | サーバーに対する各予約の上限。その `limit`、上限の下で保持されているシート数 `held`、残りの余裕 `headroom` を含みます。`limit` が `9223372036854775807` の場合は、上限が適用されていないことを示します。 | `free` は 0 に切り上げられません。負の値は、LicOps がそのサーバーで保有数を超えるシートを許可したことを意味します。通常は、シートを解放しなかったジョブのシートが原因です。 ## LicOps の運用に使うエンドポイント LicOps の運用に使うエンドポイントを次の表に示します。 | メソッド | パス | 機能 | | --- | --- | --- | | `GET` | `/api/v1/status` | LicOps が構成済みかどうか、リッスンポート、および `configurationManagement` に示される OpenLM Platform との同期状況。 | | `GET` | `/api/v1/stats` | すべてのプールとサーバー、および現在のシート数。正確なベンダー名とフィーチャー名の情報源です。 | | `GET` | `/api/v1/rules/router-admission` | LicOps が適用しているアドミッションルール (組み込みのルールを含む)。読み取り専用です。ルールは OpenLM Platform で定義します。 | | `GET` | `/api/v1/platform/servers` | LicOps が OpenLM Platform から受け取ったライセンスサーバー。受け取るまでは `503` を返します。 | | `GET`、`PUT` | `/api/v1/admission-controller/platform-credentials` | OpenLM Platform 接続を読み取る、または保存します。シークレットはマスクされた状態で返されます。 | | `POST` | `/api/v1/admission-controller/platform-credentials/check-connection` | 保存済みの資格情報ではなく、リクエストボディ内の資格情報をテストします。 | | `GET` | `/readyz` | どのリッスンポートがバインドされ、どのポートが必要とされているか。LicOps が構成を取得するまでは `503` を返します。 | | `GET` | `/health/ready`、`/health/live`、`/health/start` | OpenLM の標準のヘルスチェック。 | ## 既定値 既定の設定を次の表に示します。 | 設定 | 既定値 | 意味 | | --- | --- | --- | | API ポート | `8100` | 上記のすべてのアドレスで使用するポート。 | | LicOps のリッスンポート | `30001` | LicOps 経由でルーティングするチェックアウト用。HTTP ではなく FlexLM プロトコルで通信します。 | | Admit タイムアウト | 15 分 | この時間内に dispatch されないジョブは、シートを失います。 | | Dispatch タイムアウト | 2 時間 | 開始したジョブは、release がなくてもこの時間だけシートを保持します。 | | コールドスタート時の `Retry-After` | 10 秒 | コールドスタート時の `503` の後に待つ時間。 | | OpenLM Platform の数値 | 約 10 秒ごと | LicOps がカウントを補正する頻度。新しい数値が約 30 秒間届かないと、admit は `StaleSnapshot` で拒否します。 | タイムアウトを変更するには、[セッションのタイムアウトを設定する](https://www.openlm.com/documentation/ja/cloud/deployment-operations/licops/deployment#セッションタイムアウトを設定する) を参照してください。