문서 상태 웹후크 API 사용
문서 상태 웹훅 기능을 사용하여 수집된 문서의 상태가 available 또는 failed 가 될 때 외부 애플리케이션에 웹훅 이벤트를 전송할 수 있습니다. 웹훅 이벤트는 문서 세부사항 가져오기 API를
통해 먼저 문서 상태를 가져올 필요 없이 색인화된 문서에 대해 다음 조치를 수행하는 데 도움이 됩니다.
IBM Cloud Pak for Data 노즈비 IBM Software Hub Discovery 를 에어갭 환경에서 실행할 때는 HTTP 프록시를 통해 외부 애플리케이션에 연결해야 합니다. 더 자세한 정보는 에어갭 환경에서 HTTP 프록시 설정하기를 참고하세요.
문서 상태 웹훅 기능을 사용하려면 다음을 수행하십시오.
-
Discovery에서 웹훅 알림을 수신할 수 있는 외부 애플리케이션을 설정하십시오.
이를 수행하려면
create collection또는update collectionAPI 메소드를 사용하여 콜렉션에서 외부 애플리케이션을 웹훅 엔드포인트로 등록해야 합니다. 자세한 정보는 API 참조에서 콜렉션 작성 또는 콜렉션 업데이트 를 참조하십시오.외부 애플리케이션은 웹훅
ping이벤트를 수신하며, 이 이벤트는 웹훅이 성공적으로 작성되었음을 알립니다. IBM Cloud에서 외부 애플리케이션에 액세스할 수 있어야 합니다. -
콜렉션에 문서를 수집하십시오. 수집된 문서의 상태가
available또는failed가 되면 외부 애플리케이션이document.status웹훅 이벤트를 수신합니다.document.status웹훅 이벤트의data오브젝트에서 수집된 문서의 상태를 확인할 수 있습니다.document_ids및status매개변수는 수집된 문서의 ID및 해당 상태를 표시합니다. 자세한 정보는ping이벤트의 데이터 모델 및document.status이벤트의 데이터 모델 을 참조하십시오.
다음 이미지는 웹훅 구성의 흐름을 보여줍니다.
다음 이미지는 문서 상태 웹훅 기능 프로세스 플로우를 표시합니다.
조회 API에 대한 자세한 정보는 API 참조에서 프로젝트 API 메소드 조회 를 참조하십시오.
문서 상태 웹훅 API 기능에 대해 웹훅-doc-status-sample 애플리케이션을 참조할 수도 있습니다. 샘플 애플리케이션을 보려면 Discovery doc-tutorial-downloads 저장소에 대한 액세스 권한이 있어야 합니다.
웹훅 보안 요청 인증하기
웹훅 요청을 인증하려면 요청과 함께 전송되는 JSON 웹 토큰(JWT)을 확인하십시오. 웹훅 마이크로서비스는 자동으로 JWT를 생성하여 각 웹훅 호출과 함께 Authorization 헤더에서 전송합니다. 사용자는 JWT를 검증하는 외부 서비스에 코드를 추가해야 합니다.
시스템은 사용자가 지정하는 sample secret 를 기반으로 JWT를 생성할 수 있으며, Authorization 헤더에서 이 시스템 생성 JWT를 외부 애플리케이션에 전달할 수 있습니다. header 에 값을 지정하면 웹훅 마이크로서비스가 JWT 대신 외부 애플리케이션으로 해당 값을 전송합니다.
예를 들어, 콜렉션 작성 또는 콜렉션 업데이트 API에서 Webhook 오브젝트의 Secret 필드에 sample secret 를 지정하는 경우 Node.js:
const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
const decoded = jwt.verify(token, 'sample secret');
} catch(err) {
// error thrown if token is invalid
}
ping 이벤트의 데이터 모델
다음은 ping 이벤트 매개변수입니다.
| 매개변수 | 설명 |
|---|---|
event |
이벤트 이름은 ping 입니다. |
instance_id |
Discovery 의 인스턴스 ID입니다. |
version |
yyyy-mm-dd 형식의 Discovery API 버전입니다. |
data |
이벤트 정보가 있는 객체:
|
created_at |
이벤트가 생성된 날짜와 시간입니다. |
예를 들어, 다음은 웹훅으로 전송되는 ping 이벤트입니다.
POST https://example.com/webhook
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
"event": "ping",
"version": "2023-03-31",
"instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
"data": {
"url": "https://example.com/webhook",
"events": [
"document.status"
],
"metadata": {
"project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
"collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b"
}
},
"created_at": "2023-08-16T08:34:46.000Z"
}
document.status 이벤트의 데이터 모델
다음은 document.status 이벤트 매개변수입니다.
| 매개변수 | 설명 |
|---|---|
event |
이벤트 이름은 document.status 입니다. |
instance_id |
Discovery 의 인스턴스 ID입니다. |
version |
yyyy-mm-dd 형식의 Discovery API 버전입니다. |
data |
이벤트 특정 정보 ( project_id, collection_id 및 document_ids) 가 있는 오브젝트입니다. |
status |
문서의 상태. |
created_at |
이벤트가 생성된 날짜와 시간입니다. |
예를 들어, 다음은 웹훅으로 전송되는 document.status 이벤트입니다.
POST https://example.com/webhook
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
"event": "document.status",
"version": "2023-03-31",
"instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
"data": {
"project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
"collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b",
"document_ids": [
"1a5d4916-6097-4150-977a-ca897226565b",
"2a5d4916-6097-4150-977a-ca897226565b"
],
"status": "available"
},
"created_at": "2023-08-16T08:34:46.000Z"
}