コンテンツにスキップ

ブランド識別子を変更



POST /api/v1/account/change_brand_key

概要

アカウントのブランド識別子を一括変更します。

呼び出し前の準備と使用手順

w 権限の External 認証情報が必要です。accountUUIDs はアカウント一覧から取得します。brandKey は対象サイトの管理者が提供し、そのサイトで許可された集合に属している必要があります。アカウントの brandKey と更新時刻のみを変更し、アカウントプロフィールのキャッシュをクリアします。ワークスペース、メンバーロール、履歴データは移行せず、ワークスペース自体のブランドも変更しません。切り替える前に、対象ブランドのログインエントリーポイントと連携設定が準備済みであることを確認してください。

リクエストヘッダー

パラメータ名 型 必須 説明
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 リクエストパラメータ

パラメータ名 型 必須 説明
accountUUIDs[*] string 単一の対象アカウント UUID 文字列です。ワークスペース UUID ではありません。
例: acnt_example001
取得または入力方法: アカウント一覧の content.data[].uuid から項目ごとに取得します。
accountUUIDs array Y 対象アカウント UUID の配列です。クライアントはまず範囲を確認し、空でない文字列リストを送信してください。空の配列ですべてのアカウントが一括で影響を受けることはなく、不明な UUID または削除済み UUID は無視されます。
null を許可: False
例: ["acnt_example001"]
取得または入力方法: アカウント一覧の content.data[].uuid から項目ごとに取得します。wksp_ ワークスペース UUID を入力しないでください。
brandKey string Y 必須の文字列です。ブランド Web サイトの URL ではありません。
null を許可: False
例: guance
取得または入力方法: サイト管理者に対象サイトで許可されているブランド識別子を確認します。

パラメータの補足説明

サイトレベルの External API 認証情報を使用します。認証方式はExternal API 署名認証を参照してください。以下の例では v20240417 署名バージョンを使用します。署名パス、Query エンコード、元のリクエストボディは、実際に送信する内容と完全に一致している必要があります。返されるアカウントプロフィールには password フィールドは含まれません。mfaSecret は固定のマスク値のみであり、ログインに使用できるキーではありません。同じ対象 brandKey を重複して送信した場合も更新時刻が変わる可能性があります。この操作によって既存のログイン Token が強制的に失効することはありません。

リクエスト例

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/change_brand_key'
query = {}
data = {'accountUUIDs': ['acnt_example001'], 'brandKey': 'guance'}
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 boolean 成功時は true です。空の配列、不明な UUID、削除済み UUID はどのアカウントも変更せず、true が返る場合もあります。
{
  "code": 200,
  "content": true,
  "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 をトップレベルとして送信しないでください。
406 ft.InvalidBrandKey brandKey が対象サイトで許可された集合内にありません ブランド識別子 {} は無効です。 サイト管理者にそのサイトで許可されているブランド識別子を確認し、元の値を入力してください。
500 ft.InternalServerError データベース、キャッシュ、非同期タスクの投入、または明示的に処理されていないフィールドの異常 内部エラー traceId を保存して管理者に連絡してください。書き込みリクエストの場合は、まずアカウントの現在の状態を再取得し、確認したうえで再試行するか判断してください。500 を直ちに「未反映」と見なすことはできません。

フィードバック

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