コンテンツにスキップ

変更



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 オブジェクトを使用します。
email 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 を直ちに未適用とみなすことはできません。

フィードバック

このページは役に立ちましたか?