콘텐츠로 이동

워크스페이스 AI 전체 스위치 일괄 설정



POST /api/v1/workspace/ai_analysis/batch_set

개요

워크스페이스 AI 전체 스위치를 일괄 설정합니다.

호출 전 및 사용 단계

먼저 워크스페이스 목록에서 모든 대상 활성 워크스페이스를 확인합니다. 중복 UUID는 한 번만 계산되며, 반환되는 count는 중복 제거 후의 요청 워크스페이스 수이고 변경이 발생한 워크스페이스 수가 아닙니다. 이 작업은 워크스페이스의 enableAI만 수정하며 인시던트 자동 분석 설정은 변경하지 않습니다. 전체 스위치를 끈 뒤에도 기존 인시던트 설정 값은 유지되므로, 특정 기능을 꺼진 상태로 유지하려면 두 가지 스위치를 각각 관리해야 합니다. 동일한 값을 설정해도 성공할 수 있으며, 실제로 변경이 발생한 경우에만 해당 상태 변경 감사가 기록됩니다. 알림 설정 갱신은 비동기로 실행되며, 작업 대기열 등록에 실패하면 로그가 기록되더라도 여전히 성공을 반환할 수 있습니다.

요청 헤더

매개변수명 유형 필수 설명
X-Df-SVersion string 예시와 일치해야 하며, 이를 생략한 후 이 알고리즘을 계속 사용할 수는 없습니다.
예시: v20240417
획득 또는 입력 방법: 이 페이지의 원본 경로 및 요청 본문 서명 알고리즘과 함께 입력합니다.
X-Df-Access-Key string Y 여기 일곱 항목은 모두 쓰기 작업이므로 External 쓰기 권한이 필요합니다.
예시: <external-access-key>
획득 또는 입력 방법: 사이트 관리자가 w 권한을 가진 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>
획득 또는 입력 방법: 함께 제공되는 SK로 External API 서명 인증 및 아래 Python 템플릿에 따라 계산합니다.
X-Df-Timestamp string Y 예시의 고정 시간을 재사용할 수 없으며, 사이트 서명 유효 기간 내에 있어야 합니다.
예시: 1785427200
획득 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초를 생성합니다.

Body 요청 매개변수

매개변수명 유형 필수 설명
workspaceUUIDs[*] string 단일 활성 워크스페이스 UUID로, 앞뒤 공백을 제거한 후 순서를 유지한 중복 제거에 참여합니다.
예시: wksp_example001
획득 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 항목별로 가져옵니다.
enableAI boolean Y 필수 JSON 불리언 값입니다. enableAIAnalysis를 동시에 변경하지 않습니다.
null 허용: False
예시: true
획득 또는 입력 방법: 비즈니스 목표에 따라 true로 켜고 false로 끄며, 문자열이 아닙니다.
workspaceUUIDs array Y 필수 비어 있지 않은 문자열 배열이며, 항목별로 앞뒤 공백을 제거하고 최초 등장 순서대로 중복을 제거합니다. 하나의 워크스페이스라도 유효하지 않으면 전체 배치가 먼저 실패합니다. 계정 UUID나 수집 Token을 입력하지 마십시오.
null 허용: False
예시: ["wksp_example001"]
획득 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 대상 워크스페이스를 선택하며, 각 워크스페이스는 활성 status=0이어야 합니다.

매개변수 추가 설명

w 권한을 가진 사이트 수준 External API 자격 증명을 사용합니다. 인증 방식은 External API 서명 인증을 참조하십시오. 예시는 v20240417에 따라 서명을 계산하며, 서명과 전송은 동일한 경로, Query 및 원본 요청 본문을 사용합니다. 모든 예시는 데모 값이므로 실행 전에 실제 대상으로 교체하십시오. 쓰기 요청이 타임아웃되거나 500이 발생하면 먼저 현재 상태를 조회하고 확인한 후 재시도 여부를 결정해야 합니다. API 성공이 알림 파이프라인이 새 상태를 이미 소비했음을 의미하지 않으므로 실제 신규 이벤트와 함께 검증하십시오.

요청 예시

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/workspace/ai_analysis/batch_set'
query = {}
data = {'workspaceUUIDs': ['wksp_example001'], 'enableAI': True}
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, application/json, 통합 응답 셸입니다. 비즈니스 결과는 content에 있으며, External은 declaration을 자동 주입하지 않습니다. 워크스페이스 객체의 declaration은 자체 저장 필드입니다.

필드 유형 설명
content.workspaceUUIDs 문자열 배열 공백 제거 및 순서 유지 중복 제거 후의 활성 워크스페이스 UUID입니다.
content.count integer 중복 제거 후의 요청 워크스페이스 수이며 실제 변경 수가 아닙니다.
content.enableAI boolean 이번에 모든 대상 워크스페이스에 설정한 스위치 값입니다.
{
  "code": 200,
  "content": {
    "workspaceUUIDs": [
      "wksp_example001"
    ],
    "count": 1,
    "enableAI": true
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

아래 표는 이 API의 비즈니스 검증 및 확인된 주요 오류 분기를 나열합니다. 다운스트림 서비스는 구체적 오류 매핑에 따라 다른 4xx 오류를 반환할 수도 있습니다. 일반 5xx 및 알 수 없는 예외는 전역 처리되어 ft.InternalServerError를 반환합니다. 쓰기 요청은 현재 설정과 오류 content를 함께 확인하여 이미 적용되었는지 판단해야 하며, HTTP 상태만으로 롤백을 추론할 수 없습니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방식
406 ft.ParameterValidationFailed 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 매개변수 파싱 실패 매개변수 위치, 필드명, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문 무효 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError JSON 최상위가 객체가 아님 일부 json 파일 형식 오류 매개변수 표에 맞게 JSON 객체를 제출하고, 배열이나 null을 전체 요청 본문으로 사용하지 마십시오.
400 ft.ParamsValidateError 요청 비즈니스 검증에서 스위치가 불리언이 아니거나 UUID 목록이 비었거나 요소가 비어 있지 않은 문자열이 아님 매개변수 검증 실패: {} JSON 불리언 스위치와 비어 있지 않은 문자열 UUID 배열을 사용합니다.
401 ft.WKSPNotExistOrReleased 대상 워크스페이스 중 하나라도 존재하지 않거나, 삭제되었거나, 활성 status=0이 아님 워크스페이스가 존재하지 않음/또는 릴리스됨 워크스페이스 목록을 다시 읽고 전체 배치 대상을 수정한 후 재시도합니다.
500 ft.InternalServerError 데이터베이스, 캐시, 리소스 서비스 또는 처리되지 않은 매개변수 변환 예외 내부 오류 traceId를 저장하고 관리자에게 문의합니다. 먼저 설정과 다운스트림 실제 상태를 조회하고, 실패 응답을 곧바로 저장되지 않은 것으로 간주하지 말며, 무작정 반복 생성하거나 교체하지 마십시오.

관련 문서

문서 평가

이 페이지가 도움이 되었나요?