웹훅을 사용하여 알림 설정

Apigee Edge 문서입니다.
Apigee X 문서로 이동 정보

웹훅이란 무엇인가요?

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

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

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

웹훅 관리

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

UI를 사용하여 Webhook 관리

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

Webhooks 페이지 살펴보기

아래 설명에 따라 Webhooks 페이지에 액세스합니다.

Edge

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

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

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

그림에 강조 표시된 것처럼 웹훅 페이지에서 다음을 수행할 수 있습니다.

Classic Edge (Private Cloud)

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

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

  2. 관리 > 웹훅을 선택합니다.

Webhooks 페이지가 표시됩니다.

Webhooks 페이지에서는 다음을 할 수 있습니다.

UI를 사용하여 웹훅 추가

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

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

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

UI를 사용하여 웹훅 수정

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

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

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

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

  1. Webhooks 페이지에 액세스합니다.
  2. Webhook 위로 커서를 가져가 상태 스위치를 전환하여 사용 설정 또는 중지합니다.

UI를 사용하여 Webhook 삭제

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

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

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

API를 사용하여 Webhook 관리

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

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

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

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를 사용하여 webhook 보기

/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를 사용하여 webhook 추가

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

예를 들어 다음은 webhook3라는 webhook을 만들고 webhook에 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를 사용하여 webhook 수정

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

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

curl -X PUT "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 요청을 실행하여 웹훅을 사용 설정하거나 사용 중지하고 요청 본문에서 사용 설정된 속성을 각각 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를 사용하여 webhook 삭제

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

진행 중인 프로세스가 있는 경우 webhook을 강제로 삭제할지 여부를 지정하려면 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

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

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

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

    참고: +알림 작업이 표시되려면 요금제가 게시되어야 합니다.

기존 Edge (프라이빗 클라우드)

알림 페이지에 액세스하려면 다음 단계를 따르세요.

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

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

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

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

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

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

  3. 알림 조건을 추가하려면 +추가를 클릭하고 4단계를 반복합니다.
  4. 알림이 트리거될 때 콜백 처리를 관리할 webhook을 하나 이상 선택하여 Webhook에서 알림 작업을 설정합니다.
  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를 사용하여 webhook 만들기에서 정의한 webhook의 ID입니다.

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

{
    "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회까지 요청을 재시도합니다.

참고: Webhook 요청의 읽기 및 연결 시간 제한은 각각 3초이므로 요청이 실패할 수 있습니다.
Other response 요청 실패 시스템에서 요청을 다시 시도하지 않습니다.