웹훅을 사용하여 알림 설정

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동
정보

웹훅이란 무엇인가요?

웹훅은 이벤트에 의해 트리거되는 HTTP 콜백 핸들러를 정의합니다. 알림 템플릿을 사용하여 알림 설정에 설명된 대로 수익 창출 알림 템플릿을 사용하는 대신 웹훅을 만들고 이벤트 알림을 처리하도록 구성할 수 있습니다.

웹훅을 사용하여 알림을 설정하려면 Edge Management UI 또는 Management and Monetization API를 사용하여 다음 단계를 완료하세요.

  1. UI 또는 API를 사용하여 알림 이벤트의 콜백 핸들러를 정의하는 웹훅을 추가합니다.
  2. 콜백 핸들러를 설정합니다.
  3. UI 또는 API를 사용하여 조정 가능한 요금제의 알림을 설정합니다.

웹훅 관리

UI 또는 API를 사용하여 알림 이벤트의 콜백 핸들러를 정의하는 웹훅을 추가하고 관리합니다.

UI를 사용하여 웹훅 관리

다음 섹션에 설명된 대로 UI를 사용하여 알림 이벤트의 콜백 핸들러를 정의하는 웹훅을 추가하고 관리합니다.

웹훅 페이지 살펴보기

아래에 설명된 대로 웹훅 페이지에 액세스합니다.

에지

Edge UI를 사용하여 웹훅 페이지에 액세스하려면 다음 안내를 따르세요.

  1. apigee.com/edge에 로그인합니다.
  2. 왼쪽 탐색 메뉴에서 게시 > 수익 창출 > 웹훅을 선택합니다.

웹훅 페이지가 표시됩니다.

그림에 강조 표시된 것처럼 웹훅 페이지를 사용하면 다음 작업을 할 수 있습니다.

Classic Edge (Private Cloud)

Classic Edge UI를 사용하여 웹훅 페이지에 액세스하려면 다음 안내를 따르세요.

  1. http://ms-ip:9000에 로그인합니다. 여기서 ms-ip는 관리 서버 노드의 IP 주소 또는 DNS 이름입니다.
  2. 관리자 > 웹훅을 선택합니다.

웹훅 페이지가 표시됩니다.

웹훅 페이지에서는 다음 작업을 할 수 있습니다.

UI를 사용하여 웹훅 추가

UI를 사용하여 웹훅을 추가하려면 다음 안내를 따르세요.

  1. 웹훅 페이지에 액세스합니다.
  2. + 웹훅을 클릭합니다.
  3. 다음 정보를 입력합니다 (모든 입력란이 필수임).
    필드 설명
    이름 웹훅의 이름입니다.
    URL 이벤트 알림이 트리거될 때 호출될 콜백 핸들러의 URL입니다. 콜백 핸들러 설정을 참조하세요.
  4. 저장을 클릭합니다.

웹훅이 목록에 추가되고 기본적으로 사용 설정됩니다.

UI를 사용한 웹훅 수정

UI를 사용하여 웹훅을 수정하려면 다음 안내를 따르세요.

  1. 웹훅 페이지에 액세스합니다.
  2. 수정하려는 웹훅 위에 커서를 놓고 작업 메뉴에서 아이콘을 클릭합니다.
  3. 필요에 따라 웹훅 필드를 수정합니다.
  4. 웹훅 업데이트를 클릭합니다.

UI를 사용하여 웹훅 사용 설정 또는 중지

UI를 사용하여 웹훅을 사용 설정 또는 중지하려면 다음 안내를 따르세요.

  1. 웹훅 페이지에 액세스합니다.
  2. 웹훅 위에 커서를 놓고 상태 스위치를 전환하여 사용 설정 또는 사용 중지합니다.

UI를 사용하여 웹훅 삭제

UI를 사용하여 웹훅을 삭제하려면 다음 안내를 따르세요.

  1. 웹훅 페이지에 액세스합니다.
  2. 삭제하려는 웹훅 위에 커서를 놓고 를 클릭합니다.

웹훅이 삭제되고 목록에서 삭제됩니다.

API를 사용하여 웹훅 관리

다음 섹션에 설명된 대로 API를 사용하여 웹훅을 추가하고 관리합니다.

API를 사용하여 모든 웹훅 보기

/mint/organizations/{org_name}/webhooks에 GET 요청을 실행하여 모든 웹훅을 봅니다. 예를 들면 다음과 같습니다.

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

다음은 반환되는 응답의 예입니다.

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

API를 사용하여 웹훅 보기

/mint/organizations/{org_name}/webhooks/{webhook_id}에 GET 요청을 실행하여 단일 웹훅을 확인합니다.

예를 들면 다음과 같습니다.

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

다음은 응답의 예시입니다.

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

API를 사용하여 웹훅 추가

/mint/organizations/{org_name}/webhooks에 POST 요청을 실행하여 웹훅을 추가합니다. 웹훅의 이름과 이벤트 알림이 트리거될 때 호출될 콜백 핸들러의 URL을 전달해야 합니다.

예를 들어 다음은 webhook3라는 웹훅을 만들고 웹훅에 callbackhandler3를 할당합니다.

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

다음은 응답의 예시입니다.

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

API를 사용하여 웹훅 수정

/mint/organizations/{org_name}/webhooks/{webhook_id}에 POST 요청을 실행하여 웹훅을 수정합니다. 요청 본문에 업데이트를 전달합니다.

예를 들어 다음은 webhook1와 연결된 콜백 핸들러를 업데이트합니다.

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

다음은 응답의 예시입니다.

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

API를 사용하여 웹훅 사용 설정 또는 중지

웹훅을 업데이트할 때처럼 /mint/organizations/{org_name}/webhooks/{webhook_id}에 POST 요청을 실행하여 웹훅을 사용 설정 또는 사용 중지하고 요청 본문의 enabled 속성을 각각 true 또는 false로 설정합니다. 웹훅을 사용 중지하면 이벤트가 발생할 때 웹훅이 트리거되지 않습니다.

예를 들어 다음은 webhook3를 사용 설정합니다.

curl -X POST  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

다음은 응답의 예시입니다.

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

API를 사용한 웹훅 삭제

/mint/organizations/{org_name}/webhooks/{webhook_id}에 DELETE 요청을 실행하여 웹훅을 삭제합니다.

진행 중인 프로세스가 있는 경우 웹훅을 강제로 삭제할지 여부를 지정하려면 forceDelete 쿼리 매개변수를 true 또는 false로 설정합니다. forceDelete 쿼리 매개변수는 기본적으로 사용 설정 (true)되어 있습니다.

예를 들어 다음은 webhook3를 삭제합니다.

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

콜백 핸들러 설정

다음은 이벤트 알림이 트리거될 때 웹훅에서 정의한 콜백 핸들러로 전송되는 JSON 요청의 형식을 보여줍니다. 콜백 핸들러가 요청을 적절하게 처리하는지 확인해야 합니다.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

조정 가능한 요금제의 알림 설정

UI 또는 API를 사용하여 조정 가능한 요금제에 대해 웹훅을 사용하여 알림을 설정합니다.

UI를 사용하여 조정 가능한 요금제의 알림 설정

아래에 설명된 대로 UI를 사용하여 조정 가능한 요금제에 대해 웹훅을 사용하여 알림을 설정합니다.

조정 가능한 요금제의 알림 대화상자에 액세스

아래에 설명된 대로 조정 가능한 요금제의 알림 대화상자에 액세스합니다.

에지

Edge UI를 사용하여 알림 대화상자에 액세스하려면 다음 단계를 따르세요.

  1. 조정 가능한 알림 요금제 세부정보 지정에 설명된 대로 조정 가능한 알림 요금제를 만들고 게시합니다.
  2. 왼쪽 탐색 메뉴에서 게시 > 수익 창출 > 요금제를 선택하여 요금제 페이지에 액세스합니다.
  3. 게시된 조정 가능 알림 요금제 위에 커서를 가져가면 작업이 표시됩니다.
  4. +알림을 클릭합니다.

    알림 대화상자가 표시됩니다.

    참고: +Notify 작업을 표시하려면 요금제를 게시해야 합니다.

Classic Edge (Private Cloud)

알림 페이지에 액세스하는 방법:

  1. 조정 가능한 알림 요금제 세부정보 지정에 설명된 대로 조정 가능한 알림 요금제를 만듭니다.
  2. 게시 > 패키지를 선택하여 요금제를 확인합니다.
  3. 요금제의 작업 열에서 +알림을 클릭합니다.

    알림 대화상자가 표시됩니다.

UI를 사용하여 조정 가능한 요금제에 대한 알림 추가

조정 가능한 요금제에 대한 알림을 추가하려면 UI에서 다음 단계를 따르세요.

  1. 알림 대화상자에 액세스합니다.
  2. 알림을 트리거할 목표 거래 수의 비율을 지정하여 알림 간격에서 알림 조건을 설정합니다. 구체적인 내용은 다음과 같습니다.
    • 정확한 백분율을 설정하려면 시작/시작 % 필드에 백분율을 입력하고 종료 % 필드를 비워 둡니다.
    • 백분율 범위를 설정하려면 시작/종료 %종료 % 필드에 시작 및 종료 비율을 각각 입력하고 단계 % 필드에 증분 값을 입력합니다. 기본적으로 알림은 지정된 범위 내에서 10% 단위로 전송됩니다.

    Notify At 필드는 이벤트를 트리거하는 대상 거래 수의 각 비율을 반영하도록 업데이트됩니다.

  3. 추가 알림 조건을 설정하려면 +추가를 클릭하고 4단계를 반복합니다.
  4. 알림이 트리거될 때 콜백 처리를 관리하기 위한 웹훅을 하나 이상 선택하여 웹훅에서 알림 작업을 설정합니다.
  5. 알림 만들기를 클릭합니다.

UI를 사용하여 조정 가능한 요금제 알림 수정

조정 가능한 요금제의 알림을 수정하려면 UI에서 다음 단계를 따르세요.

  1. 알림 대화상자에 액세스합니다.
  2. 요금제의 작업 열에서 +알림을 클릭합니다.
  3. 수정을 클릭합니다.
  4. 필요에 따라 값을 수정합니다.
  5. 알림 저장을 클릭합니다.

UI를 사용하여 조정 가능한 요금제 알림 삭제

알림 조건 및 작업을 삭제하려면 다음 안내를 따르세요.

  1. 알림 대화상자에 액세스합니다.
  2. 요금제의 작업 열에서 +알림을 클릭합니다.
  3. 알림 삭제를 클릭합니다.

API를 사용하여 조정 가능한 요금제의 알림 설정

API를 사용하여 조정 가능한 요금제의 알림을 설정하려면 API를 사용하여 알림 조건 및 작업 관리에 설명된 절차를 따르고 이 섹션에 설명된 속성을 사용하세요.

알림 조건 (notificationCondition)을 설정하려면 다음 속성 값을 사용하세요. 자세한 내용은 알림 조건의 구성 속성을 참고하세요.

속성
RATEPLAN 조정 가능한 알림 요금제의 ID입니다.
PUBLISHED TRUE: 조정 가능한 알림 요금제를 게시해야 함을 나타냅니다.
UsageTarget 알림이 트리거되는 시점의 목표 트랜잭션 수 비율입니다.

이 속성을 사용하면 개발자가 구매한 조정 가능한 알림 요율표 요금제의 목표 거래 수에 근접하거나 도달했을 때 개발자에게 알릴 수 있습니다. 예를 들어 개발자가 조정 가능한 알림 요금제를 구매했는데 개발자의 목표 거래 수가 1, 000건으로 설정되어 있다면 거래 800건 (목표 거래 수의 80%), 거래 1,000건 (100%) 또는 거래 1,500건 (150%)에 도달했을 때 개발자에게 알릴 수 있습니다.

  • 정확한 비율을 설정하려면 %= n를 입력합니다. 예를 들어 %= 80는 목표 거래 수의 비율이 80%에 도달하면 알림을 보냅니다.
  • 백분율 범위를 설정하려면 시작 및 종료 백분율과 증분할 값(%= start to end by n)을 입력합니다. 예를 들어 %= 80 to 100 by 10 값은 목표 거래 수의 비율이 80%, 90%, 100%에 도달하면 알림을 전송합니다.

알림 작업을 설정하려면 actions에서 다음 값을 설정하세요. 자세한 내용은 알림 작업의 구성 속성을 참고하세요.

속성
actionAttribute WEBHOOK: 웹훅을 트리거합니다.
value 이전 섹션인 API를 사용하여 웹훅 만들기에서 정의한 웹훅 ID입니다.

다음은 목표 거래 수의 비율이 80%, 90%, 100%, 110%, 120%에 도달할 때 웹훅을 트리거하는 알림 조건을 만드는 방법을 보여주는 예입니다.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

알림 조건 및 작업 보기, 업데이트, 삭제에 대한 자세한 내용은 다음을 참조하세요.

웹훅 응답 코드

다음은 웹훅 응답 코드와 시스템에서 웹훅 응답 코드를 해석하는 방법을 요약한 것입니다.

응답 코드 설명
2xx 성공
5xx

요청에 실패했습니다. 시스템은 5분 간격으로 최대 3회 요청을 재시도합니다.

참고: 웹훅 요청의 읽기 및 연결 제한 시간은 각각 3초이며 이로 인해 요청이 실패할 수 있습니다.

Other response 요청에 실패했습니다. 시스템에서 요청을 재시도하지 않습니다.