変更¶
POST /api/v1/account/{account_uuid}/modify
概要¶
指定したアカウントの基本情報、ビジネス属性、セッション時間を変更します。
呼び出し前の準備と使用手順¶
w 権限の External 認証情報が必要です。パス account_uuid はアカウント一覧または作成レスポンスから取得します。更新するフィールドのみを送信し、省略した場合は既存値を保持します。attributes と customAttributes はオブジェクト全体を置き換えます。正常または無効化済みのアカウントを変更できます。この API では、アカウントの exterId、ブランド、言語、無効化状態、ワークスペースロールを変更できません。変更によりアカウント情報のキャッシュがクリアされ、変更内容に応じて関連するアラート設定が非同期で更新されます。成功しても、過去のログイン Token がすべて失効したことを意味しません。
パスパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| account_uuid | string | Y | 対象アカウントの UUID。 例: acnt_example001取得または入力方法: アカウント一覧の content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 秒文字列を生成します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| attributes | json | 任意。省略した場合は保持されます。指定した場合はオブジェクト全体を置き換え、{} でクリアします。マージパッチではありません。後続の SSO ログインで上書きされる可能性があります。null は指定できません。 null 許可: False 例: {"部門": "研究開発部"}取得または入力方法: SSO アカウント属性マッピングに従って、組織の目標となる完全なオブジェクトを指定します。 |
|
| countryCode | string | 任意。このフィールドのみを送信すると、元の携帯番号と組み合わせて検証および正規化が行われます。番号を変更する場合は、両方のフィールドをまとめて送信することを推奨します。mobile が空の場合、最終的に国番号もクリアされます。null は無効です。 空文字列を許可: True null 許可: False 例: 1取得または入力方法: mobile と組み合わせて対象の国/地域コードを送信します。 |
|
| customAttributes | json | 任意。省略した場合は保持されます。指定した場合はオブジェクト全体を置き換え、{} でクリアします。マージパッチではなく、null は指定できません。 null 許可: False 例: {"costCenter": "CC-1001"}取得または入力方法: 業務側で保存する必要がある完全な属性 KV オブジェクトを使用します。 |
|
| string | 任意。省略した場合は元の値を保持します。空文字列を指定するとクリアされ、null は無効です。現在の変更処理ではメールアドレス形式の検証は行われないため、呼び出し元で検証してください。最大長は 256 文字です。 空文字列を許可: True null 許可: False 最大長: 256 例: xxx@guance.com取得または入力方法: 通知を受信できる有効なメールアドレスを使用します。 |
||
| mobile | string | 携帯番号フィールドは countryCode とローカルの mobile の 2 部分で構成されます。+ 付きの国際番号または 00 プレフィックス付きの国際番号をサポートし、1 で始まる 11 桁の旧国内番号はデフォルトで 86 とみなせます。国番号を指定した場合は、番号全体の有効性が検証されます。任意。省略した場合は元の番号を保持します。明示的に空文字列を指定すると、番号と国番号の両方がクリアされます。null は無効です。 空文字列を許可: True null 許可: False 例: 2025550123取得または入力方法: メンバー情報から取得し、countryCode と一緒に送信することで古い国番号の使用を避けられます。 |
|
| name | string | 任意。省略した場合は元の値を保持します。空でない文字列を指定し、null を送信しないでください。 null 許可: False 例: 示例成员新名称取得または入力方法: メンバーの最新の表示ニックネームを使用します。 |
|
| password | string | 任意。省略した場合は元のパスワードを保持します。空でないパスワードは 8 文字以上で、4 種類の文字のうち少なくとも 3 種類を含む必要があります。現在、空文字列を指定すると元のパスワードを保持せず、空のパスワードハッシュに再設定されるため、クライアントは空文字列を禁止する必要があります。null は無効です。 null 許可: False 例: Changed!2026a取得または入力方法: 呼び出し元が新しい安全なパスワードを指定します。 |
|
| source | string | local、unknown、oidc、ldap の任意の列挙値。省略した場合は保持されます。現在は値を設定するのみで、exterId を自動変更したり、source と exterId の関係を検査したりしません。空文字列は書き込めますが、null は宣言上許可されていてもデータベースの 500 エラーを引き起こす可能性があるため、有効な列挙値のみを使用することを推奨します。 空文字列を許可: True null 許可: True 選択可能な値: ['local', 'unknown', 'oidc', 'ldap'] 例: oidc取得または入力方法: 実際に連携する ID プロバイダーと一致させます。ローカルアカウントには local を使用し、サードパーティアカウントは ID システムに応じて unknown、oidc、ldap のいずれかを選択します。 |
|
| tokenHoldTime | integer | 任意。省略した場合は保持されます。アカウントの無操作セッション保持時間(秒)。範囲は 1800~604800 で、null は指定できません。 空文字列を許可: False null 許可: False $maxValue: 604800 $minValue: 1800 例: 86400取得または入力方法: 組織のアカウントセキュリティポリシーに従って秒数を選択します(1800~604800)。 |
|
| tokenMaxValidDuration | integer | 任意。省略した場合は保持されます。アカウントセッションの最大有効期間(秒)。範囲は 60~2592000 で、null は指定できません。 空文字列を許可: False null 許可: False $maxValue: 2592000 $minValue: 60 例: 604800取得または入力方法: 組織のセキュリティポリシーに従って秒数を選択します(60~2592000)。 |
|
| username | string | 任意。省略した場合は元の値を保持します。この名前空間内で、削除されていない他のアカウントと重複してはいけません。username を変更しても email は自動同期されないため、必要に応じて email も同時に指定してください。null を送信しないでください。 null 許可: False 例: xxx@guance.com取得または入力方法: 新しいログインアカウント名を使用します。変更前に、同一の ID 名前空間内で使用されていないことを確認してください。 |
パラメータ補足¶
サイトレベルの External API 認証情報を使用します。認証方式はExternal API 署名認証を参照してください。以下の例では v20240417 署名バージョンを使用します。署名パス、Query エンコード、元のリクエストボディは、実際に送信する内容と完全に一致している必要があります。返されるアカウント情報には password フィールドは含まれません。mfaSecret は固定のマスクであり、ログインに使用できる鍵ではありません。source を変更しても ID プロバイダー設定は切り替わりません。サードパーティアカウントを直接 local としてマークすることは避けてください。セッション時間の新しい値は認証経路に従って有効になりますが、強制ログアウトの代替手段として使用しないでください。
表内の null/空文字列と省略は区別してください。現在の文字列型検証では、空文字列を一律に拒否しません。呼び出し元はログイン名やニックネームなどに意味のある空でない値を指定し、空値による暗黙のデフォルトに依存しないでください。
リクエスト例¶
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 = 'POST'
path = '/api/v1/account/acnt_example001/modify'
query = {}
data = {'name': '示例成员新名称', 'email': 'xxx@guance.com', 'customAttributes': {'costCenter': 'CC-1001'}}
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、Content-Type は application/json で、共通のレスポンスエンベロープです。ビジネスデータは content にあります。External API は declaration を自動的に追加せず、一覧のページネーションは content.pageInfo に保持されます。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer | サイト内のアカウントレコードの連番。情報の返却のみに使用し、他の API を呼び出す場合は uuid を使用します。 |
| content.uuid | string | アカウント UUID。以降の照会、変更、無効化、削除でこのフィールドを使用します。 |
| content.status | integer | アカウント状態: 0 は正常、2 は無効。一覧では 3(削除済み)がフィルタされ、その他の履歴状態が現れる可能性があります。 |
| content.creator | string | 作成者の ID。External で作成した場合は通常 SYS です。 |
| content.updator | string | 最終更新者の ID。まだ変更がない場合は空になることがあります。 |
| content.createAt | number | 作成時刻(Unix 秒)。 |
| content.updateAt | number | 更新時刻(Unix 秒)。更新時刻がない場合は -1 になることがあります。 |
| content.deleteAt | number | 状態操作時刻のフィールド。初期値は通常 -1 です。有効化/無効化でもこの値が書き込まれるため、これのみで削除を判断せず、status を使用してください。 |
| content.name | string | 表示ニックネーム。 |
| content.username | string | ログインアカウント名。サードパーティアカウントでは空または他のアカウントとの重複があり得ます。 |
| content.email | string | アカウントの連絡先メールアドレス。作成時に空で、username がメールアドレス形式の場合は username で補完されます。 |
| content.mobile | string | 携帯番号のローカル番号。復号して表示され、国番号は含みません。未設定の場合は空文字列です。 |
| content.countryCode | string | 携帯番号の国/地域コード(数字のみの文字列)。例: 86。未設定の場合は空文字列です。 |
| content.exterId | string | サードパーティ ID システムの一意の ID。ローカルアカウントでは通常空です。 |
| content.extend | object または null | 既存の拡張情報。user_icon のアバター URL を含む場合があります。本 API の作成時に送信した extend は現在保存されず、変更 API でもこの入力パラメータは公開されていません。 |
| content.extend.user_icon | string | 任意のアバター URL または静的リソースのファイル名。過去の情報を読み取る際に現れることがあり、本ページで書き込み可能なパラメータではありません。 |
| content.source | string | ID ソースの識別子。例: local、unknown、oidc、ldap。agent などの履歴上の内部ソースが存在する場合もあります。 |
| content.nameSpace | string | ID 名前空間。External で作成した場合はデフォルトで空です。本モジュールの公開パラメータでは設定できません。 |
| content.isUsed | integer または boolean | アカウントが使用済みかどうかのフラグ。 |
| content.agreeTerms | integer | 規約同意フラグ。 |
| content.canaryPublic | boolean | カナリアフラグ。 |
| content.enableMFA | boolean | MFA を有効にするかどうか。 |
| content.mfaSecret | string | 固定マスク*********************であり、使用可能な MFA 鍵は含まれません。 |
| content.language | string | 言語識別子。zh、en、zh-hant、id、ja、ko。 |
| content.tokenHoldTime | integer | アカウントの無操作セッション保持時間(秒)。新規アカウントはサイトの安全なセッション設定に従って初期化され、サンプル値に固定されるとは限りません。 |
| content.tokenMaxValidDuration | integer | アカウントセッションの最大有効期間(秒)。新規アカウントはサイトの安全なセッション設定に従って初期化されます。 |
| content.timezone | string | タイムゾーン識別子。未設定の場合は空です。 |
| content.attributes | object | SSO 同期属性の KV オブジェクト。後続の SSO ログインで上書きされる可能性があります。キーと値は連携先が取り決めます。 |
| content.attributes.{属性名} | 任意の JSON 値 | カスタム属性値。文字列の使用を推奨します。例: 部門=研究開発部。 |
| content.customAttributes | object | 業務側で管理する属性 KV オブジェクト。 |
| content.customAttributes.{属性名} | 任意の JSON 値 | 業務カスタム値。文字列の使用を推奨します。例: costCenter=CC-1001。 |
| content.statusPageSubs | integer | ステータスページ購読フラグ。 |
| content.defaultWorkspace | string | アカウントのデフォルトワークスペース UUID。未設定の場合は空です。 |
| content.brandKey | string | アカウントの現在のブランド識別子。サイトで許可されたブランド集合によって決まります。 |
| content.scheduleMobile | string | スケジュール専用の携帯番号のローカル番号。未設定の場合は空です。 |
| content.scheduleEmail | string | スケジュール専用メールアドレス。未設定の場合は空です。 |
| content.ifScheduleMobileEnable | boolean | スケジュール用携帯番号を有効にするかどうか。 |
| content.ifScheduleEmailEnable | boolean | スケジュール用メールアドレスを有効にするかどうか。 |
| content.accountStatus | string | アカウントの追加ステータス識別子。未設定の場合は空です。 |
| content.userIconUrl | string または null | 既存のアバター設定に基づいて URL を生成します。アバターがない場合は null です。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "acnt_example001",
"status": 0,
"creator": "SYS",
"updator": "external",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例成员新名称",
"username": "xxx@guance.com",
"email": "xxx@guance.com",
"mobile": "",
"countryCode": "",
"exterId": "",
"extend": null,
"source": "local",
"nameSpace": "",
"isUsed": 0,
"agreeTerms": 0,
"canaryPublic": false,
"enableMFA": false,
"mfaSecret": "*********************",
"language": "zh",
"tokenHoldTime": 86400,
"tokenMaxValidDuration": 604800,
"timezone": "",
"attributes": {
"部門": "研究開発部"
},
"customAttributes": {
"costCenter": "CC-1001"
},
"statusPageSubs": 0,
"defaultWorkspace": "",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": "",
"userIconUrl": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答の説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエストボディ JSON の最上位がオブジェクトではありません | 一部の JSON ファイル形式エラー | JSON オブジェクトを使用し、配列、文字列、null を最上位として送信しないでください。 |
| 404 | ft.NotFoundAccount | 検索条件を満たすアカウントが見つからないか、アカウントがすでに削除されています | 指定されたアカウントが見つかりません | アカウント一覧から有効な uuid を再取得してください。2 条件の照会では、2 つの値が同じアカウントに属するか確認してください。 |
| 400 | ft.InvalidPasswordRule | ローカル作成時のパスワードが null、空文字列、または強度ルールに適合していません。変更時に指定した空でないパスワードが強度ルールに適合していません | 無効なパスワードルール | パスワードは 8 文字以上で、数字、大文字、小文字、特殊文字の 4 種類のうち少なくとも 3 種類を含める必要があります。 |
| 400 | ft.UsernameExterIdExists | username が同一名前空間内の削除されていない他のアカウントによって使用されています | username/exterId はすでに存在します | 未使用のログイン名を選択してください。先に一覧を照会して既存アカウントを確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、非同期タスク配信、または明示的に処理されていないフィールドの異常 | 内部エラー | traceId を保存して管理者に連絡してください。書き込みリクエストの場合は、まずアカウントの現在の状態を再照会し、確認してから再試行するか決定してください。500 を直ちに未適用とみなすことはできません。 |