브랜드 식별자 수정¶
POST /api/v1/workspace/change_brand_key
개요¶
지정된 워크스페이스에 적용할 사이트 브랜드를 일괄 설정합니다.
호출 전 및 사용 단계¶
External API 쓰기 권한이 필요합니다. 먼저 대상 사이트에서 허용되는 브랜드 식별자를 확인하고, 워크스페이스 목록에서 유효한 UUID를 가져옵니다. 제출한 후 워크스페이스 상세를 각각 호출하여 content.brandKey를 확인합니다. 찾을 수 없는 UUID와 삭제된 워크스페이스는 건너뛰며, 응답에는 항목별 업데이트 결과가 제공되지 않습니다.
DF_EXTERNAL_API_URL, DF_EXTERNAL_ACCESS_KEY, DF_EXTERNAL_SECRET_KEY를 설정한 후 예제를 실행합니다. 예제의 워크스페이스 UUID, 브랜드 및 설정 값을 실제 값으로 바꾸며, 서명 버전은 v20240417입니다.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 서명 버전이며, 다음 예제에서는 v20240417을 사용합니다. 예: v20240417가져오기 또는 입력 방법: 예제와 동일하게 입력하며 서명 알고리즘에 대응합니다. |
|
| X-Df-Access-Key | string | Y | 요청 AK 정보 예: <access-key>가져오기 또는 입력 방법: External API 관리자가 할당합니다. |
| X-Df-Signature | string | Y | 서명 정보 예: <hex-signature>가져오기 또는 입력 방법: 예제에 따라 메서드, nonce, 경로, 타임스탬프 및 실제 전송된 JSON 바이트에 대해 HMAC-SHA256을 계산합니다. |
| X-Df-Timestamp | string | Y | 요청 시 타임스탬프 예: 1785456000가져오기 또는 입력 방법: 호출 시점의 현재 Unix 초를 입력합니다(예: date +%s 실행). |
| X-Df-Nonce | string | Y | 요청 시 생성되는 임시 코드 예: b53b47e12e514616ad8cb1f17cb66dce가져오기 또는 입력 방법: 매 요청마다 새로운 임의 값을 생성합니다(예: uuid.uuid4().hex). |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| brandKey | string | Y | 사이트에서 허용되는 브랜드 식별자입니다. 예를 들어 일부 사이트에서는 guance 또는 truewatch를 허용합니다. 빈 문자열을 전달하면 현재 사이트의 기본 브랜드를 사용합니다. null 허용: False 예: truewatch가져오기 또는 입력 방법: 대상 사이트 관리자가 활성화한 브랜드 식별자를 제공합니다. |
| workspaceUUIDs | array | Y | 워크스페이스 UUID 배열입니다. 빈 배열은 워크스페이스를 업데이트하지 않습니다. null 허용: False 예: ["wksp_example"]가져오기 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 조정할 워크스페이스를 복사하며, 비어 있지 않은 배열을 제출하는 것이 좋습니다. |
매개변수 추가 설명¶
대상 사이트에서 할당한 External API 서명 자격 증명을 사용합니다.
요청 예제¶
import hmac
import json
import os
import time
import uuid
import requests
server = os.environ["DF_EXTERNAL_API_URL"].rstrip("/")
path = "/api/v1/workspace/change_brand_key"
method = "POST"
body = json.dumps({'brandKey': 'truewatch', 'workspaceUUIDs': ['wksp_example']}, ensure_ascii=False, separators=(',', ':')).encode('utf-8')
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
payload = f"{method} {nonce} {path} {timestamp} ".encode("utf-8") + body
signature = hmac.digest(os.environ["DF_EXTERNAL_SECRET_KEY"].encode(), payload, "sha256").hex()
headers = {
"X-Df-Access-Key": os.environ["DF_EXTERNAL_ACCESS_KEY"],
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-SVersion": "v20240417",
"X-Df-Signature": signature,
"Content-Type": "application/json",
}
response = requests.request(method, server + path, headers=headers, data=body, timeout=15)
response.raise_for_status()
data = response.json()["content"]
응답¶
HTTP 200, application/json.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | 성공 응답은 {}이며, 항목별 결과가 없습니다. |
{
"code": 200,
"content": {},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 필드 유형, 필수 여부 또는 제약 조건이 매개변수 표와 일치하지 않음 | 요청 필드 검증에 실패했으며, 메시지에 필드 또는 규칙이 표시됩니다. | 필드, 유형 및 제약 조건을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류입니다. | content의 reason, line 및 column을 읽은 후 수정합니다. |
| 400 | ft.JsonFormatError | JSON 형식은 유효하지만 전체 Body가 JSON 객체가 아님 | JSON 형식 오류입니다. | 매개변수를 중괄호로 구성된 JSON 객체 안에 넣습니다. |
| 406 | ft.InvalidBrandKey | 브랜드 식별자가 현재 사이트의 허용 집합에 없음 | 브랜드 식별자가 유효하지 않습니다. | 사이트 관리자에게 사용 가능한 브랜드 식별자를 확인하거나 빈 문자열을 사용하여 기본값으로 복원하도록 요청합니다. |