マッピング設定一覧¶
GET /api/v1/login_mapping/field/list
概要¶
システムログインマッピングおよび現在解決可能なワークスペース名、ロール名をページングして照会します。
呼び出し前と使用手順¶
デフォルトでは、本サービスのすべてのワークスペースにある未削除のシステムマッピングを照会します。workspaceUUID を使用して1つのワークスペースに絞り込めます。search はロール名、アクティブワークスペース名、ソースフィールド名、ソースフィールド値に対して部分一致を行います。属性の完全一致条件によるフィルタではありません。更新日時の降順で並べ、未更新の場合は作成日時を使用します。デフォルトは pageIndex=1/pageSize=20 で、最大 100 です。ルールの対象ロールが削除されている場合、targetValues には古い UUID が残る可能性があります。roles には解決可能な有効ロールのみが表示されます。解決可能なロールがない場合、roles フィールドは省略されることがあります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略したまま本ページのアルゴリズムを引き続き使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 読み取り API では r または w の資格情報を使用でき、書き込み API では w の資格情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI Key は使用できません。 |
| X-Df-Nonce | string | Y | 一時的なナンス。失敗して再送する場合も新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字のメソッド、nonce、元の完全なパス、timestamp、元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 を実行して hex ダイジェストを取得します。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証 に従い、対応する SK を使用して計算します。完全に動作するテンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイト設定の署名有効時間枠内である必要があり、例の時刻を再利用することはできません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | デフォルトは 1、最小値は 1。 null を許可: False $minValue: 1 例: 1取得または入力方法: 1 から開始し、content.pageInfo に従って次のページへ進みます。 |
|
| pageSize | integer | デフォルトは 20、最大 100。 null を許可: False $maxValue: 100 $minValue: 1 例: 20取得または入力方法: クライアント表示に合わせて 1~100 を選択します。 |
|
| search | string | 任意。先頭と末尾の空白を除去したうえで部分一致。複数カテゴリに一致した場合はいずれかに一致すれば対象となり、省略または空白のみの場合はフィルタしません。 null を許可: False 例: 研发部取得または入力方法: ソース属性名、値、ロール名、またはワークスペース名のキーワードを使用します。 |
|
| workspaceUUID | string | 任意。省略または空文字列の場合はすべてのワークスペースのシステムルールを照会し、特定のワークスペースを自動選択しません。 null を許可: False 例: wksp_example001取得または入力方法: ワークスペース一覧 の content.data[].uuid から取得します。 |
パラメータの補足説明¶
認証方式はExternal API 署名認証を参照してください。本モジュールはサイトのシステムログインマッピング(isSystem=1)を管理し、OIDC/LDAP など共有ログインマッピング経路を使用するサードパーティログインで使用されます。ワークスペースのカスタムマッピングや独立した SAML 設定 API ではありません。設定を保存しても既存ユーザーすべての権限が直ちに一括再計算されるわけではなく、後続の関連ログイン時にモードに従って処理されます。
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 対象サイトのアドレスおよび管理者が割り当てた External API AK/SK に置き換えます。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/login_mapping/field/list'
query = {'workspaceUUID': 'wksp_example001', 'search': '研发部', 'pageIndex': 1, 'pageSize': 20}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
レスポンス¶
HTTP 200、application/json の共通エンベロープ。External は declaration を自動注入しません。リストのページネーションは content.pageInfo にあります。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | オブジェクト配列 | このページの未削除システムマッピング。結果が空の場合は []。 |
| content.data[].id | integer または null | レコード通番。作成スナップショットでは null になる場合があり、操作には uuid を使用します。 |
| content.data[].uuid | string | マッピングレコードの UUID。通常は lgmp_ プレフィックスです。 |
| content.data[].status | integer | ルールステータス。有効は 0 です。リストでは 3 をフィルタしますが、履歴上の他のステータスが含まれる場合があります。実際のログイン時の消費および変更/削除では 0 のみを処理します。 |
| content.data[].creator | string | 作成者の識別情報。External では通常 sys です。 |
| content.data[].updator | string | 更新者の識別情報。未更新の場合は空になることがあります。 |
| content.data[].createAt | integer | 作成 Unix 秒。 |
| content.data[].deleteAt | integer | 削除 Unix 秒。未削除の場合は通常 -1 です。 |
| content.data[].updateAt | integer | 更新 Unix 秒。未変更の場合は通常 -1 です。 |
| content.data[].sourceField | string | マッチング対象の元の userinfo トップレベル属性名。 |
| content.data[].sourceValue | string | マッチング対象の属性文字列値。 |
| content.data[].targetValues | 文字列配列 | 保存された対象ロール UUID のリスト。履歴のリスト項目からロールが依然有効であると直接断定することはできません。 |
| content.data[].targetValues[] | string | 単一の対象ロール UUID。 |
| content.data[].workspaceUUID | string | このルールの対象ワークスペース UUID。 |
| content.data[].isSystem | integer または boolean | 本モジュールではシステムマッピング、1 または true。ワークスペースのカスタムルールではありません。 |
| content.data[].workspaceName | string または null | 現在のアクティブワークスペース名。ワークスペースが無効/削除済み/解決不可の場合は null になることがあります。 |
| content.data[].roles | オブジェクト配列 | 任意のロール概要。解決可能なロールがない場合は省略されることがあります。targetValues とは異なります。 |
| content.data[].roles[].uuid | string | 有効なロール UUID。 |
| content.data[].roles[].name | string | 有効なロール名。 |
| content.pageInfo.pageIndex | integer | 現在のページ番号。 |
| content.pageInfo.pageSize | integer | ページあたりの件数。 |
| content.pageInfo.count | integer | このページの件数。 |
| content.pageInfo.totalCount | integer | フィルタ条件での総数。 |
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "lgmp_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"sourceField": "department",
"sourceValue": "研发部",
"targetValues": [
"readOnly"
],
"workspaceUUID": "wksp_example001",
"isSystem": 1,
"workspaceName": "示例空间",
"roles": [
{
"uuid": "readOnly",
"name": "ReadOnly"
}
]
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
一致するルールがない場合:
{
"code": 200,
"content": {
"data": [],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 0,
"totalCount": 0
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては公共エラー定義を参照してください。
確認済みのルールとリクエストエラーを表に示します。通常のデータベース/キャッシュ/監査の異常は最終的に 500 ft.InternalServerError になります。設定がコミットされた後に後続のエラーが発生する可能性があるため、まず現在の状態を読み取ってから再試行してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 500 | ft.InternalServerError | データベース、サイト設定キャッシュ、監査、または未処理の履歴データの異常 | 内部エラー | traceId を保持し、まずルールまたはスイッチを読み取って現在の状態を確認してください。データベースとキャッシュ/監査は同一トランザクションではないため、エラーが完全に未保存であることを証明するものではありません。 |