조회¶
GET /api/v1/notify_object/get
개요¶
알림 대상 UUID를 기준으로 구성 및 사용자 정의 작업 권한 정보를 조회합니다.
호출 전 및 사용 단계¶
알림 대상 목록에서 uuid를 가져와 Query notifyObjectUUID로 전달합니다. 기존 객체에 대해서는 구성 및 권한 요약을 반환합니다. 현재 레코드를 찾지 못한 경우에도 HTTP 200이며, content에 allow_operation=null 및 공통 선언이 포함되고 404를 반환하지 않습니다. content.uuid 존재 여부로 대상 존재 여부를 판단합니다. updatorInfo는 조회 범위 제한으로 인해 빈 문자열일 수 있으므로, 이를 근거로 수정된 적이 없다고 판단해서는 안 됩니다.
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| notifyObjectUUID | string | Y | 필수 알림 대상 UUID입니다. 예: notify_example가져오기 또는 입력 방법: 알림 대상 목록에서 반환된 content.data[].uuid에서 현재 워크스페이스의 알림 대상 UUID를 복사합니다. |
파라미터 추가 설명¶
allow_operation=null은 객체의 사용자 정의 작업 권한이 활성화되지 않았음을 나타내며, API 인증이 통과되었거나 모든 수정 권한이 있음을 증명하는 것으로 간주할 수 없습니다.
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/notify_object/get' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode notifyObjectUUID=notify_example
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content | object | 객체 구성 및 권한 요약입니다. 레코드를 찾지 못한 경우 uuid 등의 엔터티 필드가 없습니다. |
| content.id | integer | 데이터베이스 번호이며, 후속 작업에는 uuid를 사용하십시오. |
| content.uuid | string | 알림 대상 UUID입니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID입니다. |
| content.name | string | 알림 대상 이름입니다. |
| content.type | string | 알림 유형입니다. 이전 Jira/ServiceNow 저장 별칭은 jiraWebhook/serviceNowWebhook으로 정규화됩니다. |
| content.optSet | object | type에 대응하는 알림 구성이며, 구체적인 필드는 아래와 같고 구성되지 않은 필드는 생략될 수 있습니다. |
| content.openPermissionSet | boolean | 이 객체의 사용자 정의 작업 권한 활성화 여부입니다. |
| content.permissionSet | array<string> |
객체 작업이 허용된 역할, 멤버 또는 팀 식별자 배열입니다. |
| content.permissionSet[] | string | 단일 권한 주체 식별자입니다. |
| content.autoDisableAt | integer | 자동 비활성화 시간(Unix 초)이며, 자동 비활성화되지 않은 경우 -1입니다. |
| content.status | integer | 레코드 상태이며 0은 활성화, 2는 비활성화입니다. 3은 삭제됨이며 이 조회에서는 반환되지 않습니다. |
| content.creator | string | 생성 주체입니다. |
| content.updator | string | 최근 업데이트 주체이며, 업데이트되지 않은 경우 비어 있습니다. |
| content.createAt | integer | 생성 Unix 초입니다. |
| content.updateAt | integer | 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1입니다. |
| content.deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content.optSet.webhook | string | 봇, Slack, Teams, Google Chat, Jira 및 ServiceNow에서 사용하는 콜백 주소입니다. Jira/ServiceNow는 유효한 HTTPS여야 하며 URL 사용자 이름/비밀번호, 프래그먼트 또는 공백을 포함할 수 없습니다. 주소는 사이트 도메인 해석 및 인트라넷 정책의 제한을 받습니다. |
| content.optSet.secret | string | DingTalk/Lark 등의 봇은 원본 서명 키를 반환할 수 있습니다. Jira는 원본 키를 반환하지 않고 hasSecret 플래그를 사용합니다. |
| content.optSet.url | string | HTTPRequest/simpleHTTPRequest의 필수 비어 있지 않은 콜백 주소이며, 도메인 해석 및 인트라넷 정책의 제한을 받습니다. |
| content.optSet.to | array<string> |
mailGroup, sms, vms의 수신 멤버/팀 UUID 배열입니다. 멤버 프로필에 해당 이메일 또는 휴대폰 번호가 구성되어 있어야 하며, 임의의 이메일/휴대폰 번호 문자열 배열이 아닙니다. |
| content.optSet.to[] | string | 단일 멤버 또는 팀 UUID입니다. |
| content.optSet.refMembers | array<string> |
HTTPRequest/simpleHTTPRequest 모두 문자열 배열을 허용하고 검증하지만, 현재 HTTPRequest만 실제로 refMembersInfo로 확장되어 콘텐츠 파싱에 참여합니다. simpleHTTPRequest는 이 확장을 수행하지 않습니다. |
| content.optSet.refMembers[] | string | 연결된 멤버 또는 팀 UUID 문자열입니다. |
| content.optSet.headersConfig | object | 사용자 정의 요청 헤더 구성입니다. Jira/ServiceNow의 headers와 다릅니다. 조회 API는 해당 민감한 값을 복원하므로, 저장 전에 반환 데이터를 적절히 처리하십시오. |
| content.optSet.headersConfig.isOpen | boolean | 구성이 존재하는 경우 반드시 불리언 값을 제공해야 하며, true인 경우에만 사용자 정의 헤더를 전송합니다. |
| content.optSet.headersConfig.items | array<object> |
구성이 존재하는 경우 반드시 배열을 전달해야 하며 최대 50개 항목입니다. isOpen=false인 경우에도 항목을 검증합니다. |
| content.optSet.headersConfig.items[] | object | 단일 사용자 정의 요청 헤더 객체입니다. |
| content.optSet.headersConfig.items[].key | string | 비어 있지 않은 문자열이며, 앞뒤 공백을 제거한 후 최대 256자이고 대소문자를 구분하지 않고 중복이 제거됩니다. |
| content.optSet.headersConfig.items[].value | string | 비어 있지 않은 문자열이며 최대 4096자입니다. |
| content.optSet.headersConfig.items[].isSensitive | boolean | 필수 불리언 값이며, true인 값은 저장 시 암호화되고 상세 및 목록에서 원래 값으로 복원됩니다. |
| content.optSet.bodyTemplate | string | HTTPRequest만 사용자 정의 요청 본문 템플릿을 지원하며, 문자열은 최대 5120자입니다. 빈 문자열 또는 null은 구성되지 않은 상태를 의미하고, 공백만 있는 경우에는 활성화되지 않습니다. 저장 시 유형과 길이만 검증하고 템플릿 구문이나 변수는 검증하지 않습니다. 실제 전송은 사이트의 템플릿 기능에 의존하므로 실제 알림으로 검증해야 합니다. simpleHTTPRequest는 비어 있지 않은 템플릿을 지원하지 않습니다. |
| content.optSet.token | string | telegramBot은 구성된 Bot Token을 반환합니다. Jira/ServiceNow는 bearer 자격 증명을 반환하지 않고 hasToken 플래그를 사용합니다. |
| content.optSet.chat_id | string | telegramBot의 필수 대상 채팅 ID 문자열입니다. |
| content.optSet.message_thread_id | string | telegramBot의 선택적 토픽 ID이며, 존재하는 경우 문자열입니다. |
| content.optSet.auth_type | string 또는 null | Jira/ServiceNow 전용입니다. null은 별도 인증 헤더를 생성하지 않으며 basic, bearer, api_key를 모두 지원합니다. secret은 Jira만 지원합니다. 생략 시 Jira는 기본값 secret, ServiceNow는 기본값 basic입니다. |
| content.optSet.username | string | Jira/ServiceNow basic 인증 사용자 이름이며, 비어 있지 않고 콜론 또는 줄 바꿈을 포함할 수 없습니다. |
| content.optSet.api_key_header | string | Jira/ServiceNow api_key 인증 헤더 이름이며 Content-Type일 수 없습니다. |
| content.optSet.headers | object | Jira/ServiceNow 전용입니다. 헤더 이름은 유효하고 대소문자를 구분하지 않으며 중복되지 않아야 하고, 값에는 줄 바꿈이 포함되지 않아야 합니다. Content-Type은 application/json만 가능합니다. 동일 주체의 업데이트에서 생략하면 기존 헤더를 유지하고, {}는 비웁니다. 조회 시 값은 마스킹되어 빈 문자열입니다. |
| content.optSet.headers.동적 키 | string | 사용자 정의 헤더의 문자열 값입니다. 업데이트 시 동일한 이름의 빈 값은 동일 주체의 이전 값을 유지할 수 있으며, 새 헤더는 비어 있을 수 없습니다. |
| content.optSet.hasSecret | boolean | Jira secret 모드 전용이며, 서명 키가 구성되었는지 여부입니다. |
| content.optSet.hasPassword | boolean | Jira/ServiceNow basic 모드 전용이며, 비밀번호가 구성되었는지 여부입니다. |
| content.optSet.hasToken | boolean | Jira/ServiceNow bearer 모드 전용이며, Token이 구성되었는지 여부입니다. |
| content.optSet.hasApiKey | boolean | Jira/ServiceNow api_key 모드 전용이며, Key가 구성되었는지 여부입니다. |
| content.optSet.hasHeaderValues | object | Jira/ServiceNow 전용이며, 반환되는 각 헤더에 비어 있지 않은 값이 저장되었는지 표시합니다. |
| content.optSet.hasHeaderValues.동적 키 | boolean | 헤더 이름에 대응하는 구성 상태입니다. |
| content.optSet.deliveryStatus | string | Jira/ServiceNow의 구성 표시 식별자이며 현재 configured이고, 실제 전달 성공을 의미하지는 않습니다. |
| content.optSet.credentialsRequired | boolean | Jira/ServiceNow에 현재 인증 방식에 필요한 자격 증명 또는 헤더 값이 아직 부족한지 여부입니다. |
| content.creatorInfo | object 또는 string | 생성자 요약이며, 정보가 없을 때 목록에서는 {}이고 상세에서는 빈 문자열일 수 있습니다. |
| content.creatorInfo.uuid | string | 계정 또는 API Key UUID입니다. |
| content.creatorInfo.status | integer | 계정 상태입니다. |
| content.creatorInfo.wsAccountStatus | integer | 워크스페이스에서의 계정 상태입니다. |
| content.creatorInfo.username | string | 사용자 이름입니다. |
| content.creatorInfo.name | string | 표시 이름입니다. |
| content.creatorInfo.iconUrl | string | 아바타 URL입니다. |
| content.creatorInfo.email | string | 이메일 또는 API Key 식별자입니다. |
| content.creatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.creatorInfo.countryCode | string | 휴대폰 번호 국가 코드이며 비어 있을 수 있습니다. |
| content.creatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 비어 있을 수 있습니다. |
| content.updatorInfo | object 또는 string | 업데이트 주체 요약이며, 정보가 없을 때 목록에서는 {}이고 상세에서는 빈 문자열일 수 있습니다. 상세는 현재 생성자 기준으로만 조회하므로, 업데이트 주체가 다르면 정보가 없을 수 있습니다. |
| content.updatorInfo.uuid | string | 계정 또는 API Key UUID입니다. |
| content.updatorInfo.status | integer | 계정 상태입니다. |
| content.updatorInfo.wsAccountStatus | integer | 워크스페이스에서의 계정 상태입니다. |
| content.updatorInfo.username | string | 사용자 이름입니다. |
| content.updatorInfo.name | string | 표시 이름입니다. |
| content.updatorInfo.iconUrl | string | 아바타 URL입니다. |
| content.updatorInfo.email | string | 이메일 또는 API Key 식별자입니다. |
| content.updatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.updatorInfo.countryCode | string | 휴대폰 번호 국가 코드이며 비어 있을 수 있습니다. |
| content.updatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 비어 있을 수 있습니다. |
| content.allow_operation | boolean 또는 null | 사용자 정의 작업 권한 계산 결과입니다. true는 허용, false는 거부입니다. null은 객체 사용자 정의 권한이 활성화되지 않았음을 의미하며, 여전히 API 권한을 충족해야 합니다. |
| content.permissionSetInfo | object | permissionSet 식별자를 키로 하는 주체 요약이며, permissionSet이 비어 있지 않은 경우에만 나타납니다. |
| content.permissionSetInfo.주체 식별자 | object | 멤버는 계정 요약이고, 팀/역할은 {name,status}이며, 유효하지 않은 주체는 빈 객체일 수 있습니다. |
| content.permissionSetInfo.주체 식별자.name | string | 팀 또는 역할 표시 이름입니다. 멤버 필드는 creatorInfo와 동일합니다. |
| content.permissionSetInfo.주체 식별자.status | integer | 주체 상태이며 0은 정상입니다. |
| content.permissionSetInfo.주체 식별자.uuid | string | 계정 또는 API Key UUID입니다. |
| content.permissionSetInfo.주체 식별자.wsAccountStatus | integer | 워크스페이스에서의 계정 상태입니다. |
| content.permissionSetInfo.주체 식별자.username | string | 사용자 이름입니다. |
| content.permissionSetInfo.주체 식별자.iconUrl | string | 아바타 URL입니다. |
| content.permissionSetInfo.주체 식별자.email | string | 이메일 또는 API Key 식별자입니다. |
| content.permissionSetInfo.주체 식별자.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.permissionSetInfo.주체 식별자.countryCode | string | 휴대폰 번호 국가 코드이며 비어 있을 수 있습니다. |
| content.permissionSetInfo.주체 식별자.acntWsNickname | string | 워크스페이스 닉네임이며 비어 있을 수 있습니다. |
| content.declaration | object 또는 null | 워크스페이스 공통 선언입니다. |
{
"code": 200,
"content": {
"id": 42,
"uuid": "notify_example",
"workspaceUUID": "wksp_example",
"name": "生产回调",
"type": "HTTPRequest",
"optSet": {
"url": "https://receiver.example.com/alerts"
},
"openPermissionSet": false,
"permissionSet": [],
"autoDisableAt": -1,
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"creatorInfo": "",
"updatorInfo": "",
"allow_operation": null,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
대상을 찾지 못한 경우
{
"code": 200,
"content": {
"allow_operation": null,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반함 | 파라미터 파싱 실패 | Query 파라미터 표 및 예시를 확인하십시오. |
| 500 | ft.InternalServerError | 구성 조회, 복호화 또는 데이터베이스 조회 실패 | 내부 오류 | traceId와 객체 UUID를 보관하여 지원팀에 문의하십시오. 읽을 수 없는 자격 증명 구성을 반복해서 복사하지 마십시오. |