新規作成¶
POST /api/v1/account/add
概要¶
ローカルアカウントを作成するか、サードパーティの exterId に基づいて連携アカウントを作成します。
呼び出し前の準備と使用手順¶
External 認証情報の w 権限が必要です。ローカルアカウントでは exterId を省略し、サードパーティ SSO アカウントでは安定した exterId を指定して password="" を明示します。source は本インターフェースの公開入力パラメータではなく、ローカルは local 固定、サードパーティは既定で unknown です。成功後は content.uuid を保存してください。アカウント作成時にワークスペースへ自動的に参加することはありません。スペースへの関連付けには、対応するメンバー管理機能を使用してください。タイムアウトまたは 500 の後は、まずアカウント一覧またはアカウント詳細で作成済みかどうかを確認してから再試行してください。作成処理は内部で先にアカウントを登録するため、冪等キーを備えていません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョンです。省略したまま本ページのアルゴリズムを継続使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例示の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 読み取りインターフェースでは r または w の認証情報を使用でき、書き込みインターフェースでは 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 マッピングルールまたは企業の ID システムから KV オブジェクトを取得します。フィールド名は連携双方で取り決めます。 |
|
| brandKey | string | 省略可能です。省略時はサイトの既定ブランドを使用します。null は指定できません。すべてのブランドサイトでこの値が許可されるものと勝手に想定しないでください。 null の許可: False 例: guance取得または入力方法: サイト管理者から許可されたブランド識別子を取得します。 |
|
| countryCode | string | 文字列の国/地域コードです。省略され、かつ mobile が旧形式の 11 桁の国内番号である場合は 86 を推測できます。mobile が空の場合は最終的に空にクリアされます。 空文字列の許可: True null の許可: False 例: 1取得または入力方法: メンバーの携帯番号が属する国/地域から取得します。たとえば中国は 86、米国は 1 です。 |
|
| customAttributes | json | 省略可能なオブジェクトで、省略時は既定で {} です。業務側で保守し、値には文字列の使用を推奨します。null は指定できません。 null の許可: False 例: {"costCenter": "CC-1001"}取得または入力方法: お客様側の業務アカウント属性から KV オブジェクトを取得します。たとえばコストセンターなどです。 |
|
| string | Y | 必須です。値がある場合はメールアドレス形式を検証します。空文字列で、かつ username がメールアドレス形式の場合は自動的に username で補完されます。null は指定できません。 空文字列の許可: True null の許可: False $isEmail: True 例: xxx@guance.com取得または入力方法: メンバーが通知を受信できる有効なメールアドレスを使用します。メールアドレスがない場合は空文字列を明示的に渡すことができます。 |
|
| extend | json | 省略可能なオブジェクトまたは null です。現在の作成実装ではこのフィールドは保存されませんが、レスポンスでは通常 null になります。 null の許可: True 例: {}取得または入力方法: 現在の宣言との互換性のためだけのものです。このフィールドに追加情報を保存することはせず、業務のカスタムデータは customAttributes に置いてください。 |
|
| exterId | string | 省略可能です。空でない値はサードパーティ作成ブランチを有効にし、空の名前空間内で一意になります。この場合 source は自動的に unknown になります。省略すると local のローカルアカウントを作成します。サードパーティの識別を表すために null や空値を渡さないでください。 空文字列の許可: False null の許可: False 例: sso-user-1001取得または入力方法: お客様側の SSO/ID プロバイダーから安定したユーザー ID を取得します。変化するニックネームは使用できません。 |
|
| isDisable | boolean | この省略可能なブール値フィールドは現在、作成状態を変更しません。新しいアカウントは status=0 のままです。isDisable=true に依存して無効化されたアカウントを作成しないでください。 null の許可: False 選択可能な値: [True, False] 例: false取得または入力方法: 新しいアカウントを無効化する必要がある場合は、作成成功後に uuid を取得して有効化/無効化を呼び出してください。 |
|
| language | string | 省略可能です。省略、null、空文字列のいずれも既定で zh になります。値がある場合は宣言された列挙値内である必要があります。 空文字列の許可: True null の許可: True 選択可能な値: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko'] 例: zh取得または入力方法: メンバーの設定に応じて zh、en、zh-hant、id、ja、ko のいずれかを選択します。 |
|
| mobile | string | 携帯電話フィールドは countryCode とローカルの mobile の 2 部分で構成されます。+ 付き国際番号または 00 プレフィックス付き国際番号をサポートし、1 で始まる 11 桁の旧国内番号は既定で 86 とみなせます。国コードを指定した場合は番号全体の有効性を検証します。省略時は既定で空になります。null を渡さないでください。 空文字列の許可: False null の許可: False 例: 2025550123取得または入力方法: メンバーの実際に有効な携帯番号のローカル番号を使用し、countryCode と組み合わせます。設定しない場合は省略します。 |
|
| name | string | Y | 必須のニックネームです。意味のある空でない文字列を指定してください。 空文字列の許可: False null の許可: False 例: 示例成员取得または入力方法: ID システムのメンバー表示名を使用します。 |
| password | string | Y | 必須です。exterId がない場合は 8 文字以上で、数字/大文字/小文字/特殊文字の 4 種類のうち少なくとも 3 種類を含む必要があります。exterId がある場合はこの強度検証を行わず、空文字列でもかまいません。null を渡さないでください。exterId がない場合は 400 ft.InvalidPasswordRule を返し、exterId がある場合はハッシュ生成に進み、500 ft.InternalServerError を返す可能性があります。 空文字列の許可: True null の許可: True 例: Example!2026a取得または入力方法: 呼び出し側がローカルアカウント用に生成して適切に配布します。サードパーティ SSO アカウントでは空文字列を明示的に指定します。 |
| username | string | Y | 必須です。exterId がない場合は空の名前空間内で一意である必要があります。exterId がある場合は重複が許可され、サードパーティは空文字列を渡すことができます。null を渡さないでください。基盤データベースは null を受け付けません。 空文字列の許可: True null の許可: True 例: xxx@guance.com取得または入力方法: ローカルアカウントは未使用のログイン名を使用し、有効なメールアドレスを推奨します。サードパーティアカウントはお客様側のログイン名を使用します。 |
パラメータの補足説明¶
サイトレベルの External API 認証情報を使用します。認証方式はExternal API 署名認証を参照してください。以下の例では v20240417 署名バージョンを使用します。署名対象のパス、Query エンコード、元のリクエストボディは実際に送信する内容と完全に一致している必要があります。返却されるアカウント情報には password フィールドは含まれません。mfaSecret は固定のマスクのみで、ログインに使用できるキーではありません。
サードパーティアカウントの最小リクエストボディ例:
ローカルパスワードは HTTPS 上の平文文字列を使用します。本インターフェースでは管理画面の RSA パスワードラッピングを使用しません。
表内の 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/add'
query = {}
data = {'username': 'xxx@guance.com', 'password': 'Example!2026a', 'name': '示例成员', 'email': 'xxx@guance.com', 'language': 'zh', 'attributes': {'部门': '研发部'}, '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 | サイト内のアカウントレコード通番です。情報として返されるのみで、他のインターフェースを呼び出す際は uuid を使用します。 |
| content.uuid | string | アカウント UUID です。以降の参照、変更、無効化、削除ではこのフィールドを使用します。 |
| content.status | integer | アカウント状態: 0 は正常、2 は無効です。リストのフィルタでは 3 は削除済みですが、その他の過去の状態が現れる場合があります。 |
| content.creator | string | 作成者の識別子です。External で作成した場合は通常 SYS です。 |
| content.updator | string | 最終更新者の識別子です。まだ変更がない場合は空になることがあります。 |
| 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 のアバターアドレスを含む場合があります。本インターフェースの作成時に渡した extend は現在保存されず、変更インターフェースもこの入力パラメータを公開していません。 |
| 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 | アカウントの付加状態識別子です。未設定の場合は空です。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "acnt_example001",
"status": 0,
"creator": "SYS",
"updator": "",
"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": ""
},
"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 をトップレベルとして送信しないでください。 |
| 400 | ft.InvalidPasswordRule | ローカル作成時のパスワードが null、空文字列、または強度ルールに適合しない。変更時に指定した空でないパスワードが強度ルールに適合しない | 無効なパスワードルール | パスワードは 8 文字以上で、数字、大文字、小文字、特殊文字の 4 種類のうち少なくとも 3 種類を含めてください。 |
| 406 | ft.InvalidBrandKey | brandKey が対象サイトの許可集合に含まれない | ブランド識別子{}が無効です。 |
サイト管理者にそのサイトで許可されているブランド識別子を確認し、元の値を入力してください。 |
| 400 | ft.ObjectParmeterExists | ローカルの username またはサードパーティの exterId に未削除のアカウントが既に存在する | <usernameまたはexterId> は既に存在します |
まず既存のアカウントを検索してください。更新には変更インターフェースを使用し、重複作成を冪等な成功として扱わないでください。 |
| 429 | ft.OperationTooFrequently | 同じ username のローカル作成ロックがまだ解放されていない | 操作が頻繁すぎます。しばらくしてから再試行してください | 待機後にまず既存のアカウントを検索してください。未作成であることを確認してから、署名リクエストを再生成してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、非同期タスク投入、または明示的に処理されていないフィールドの異常 | 内部エラー | traceId を保存して管理者に連絡してください。書き込みリクエストはまずアカウントの現状を再検索し、確認してから再試行を判断してください。500 をそのまま未適用とみなすことはできません。 |