이 페이지는 Cloud Translation API를 통해 번역되었습니다.

잠재고객 목록에 대한 웹훅 알림 받기

이 가이드에서는 웹훅을 사용하여 비동기 알림을 수신하는 방법을 설명합니다. 잠재고객 내보내기 요청의 상태를 확인하세요. 이 기능은 Data API의 v1alpha 버전에 있습니다.

웹훅 알림 Google 애널리틱스 데이터의 고급 기능입니다. API를 참고하세요. Introduction to Responsible AI를 잠재고객 내보내기 기능에 대한 자세한 내용은 잠재고객 내보내기 만들기를 참고하세요.

웹훅이 없으면 정기적으로 API를 폴링하여 요청이 완료되는 시기를 결정합니다.

Cloud Run을 사용하여 샘플 웹훅 애플리케이션 만들기

다음 단계에 따라 Google Cloud를 사용하여 샘플 웹훅 애플리케이션을 만들 수 있습니다. 빠른 시작: Cloud Run에 샘플 서비스 배포 가이드를 참조하세요.

샘플 서비스가 POST 웹훅 알림 요청을 수신 대기하려면 빠른 시작 튜토리얼의 index.js 파일을 다음으로 바꿉니다. 코드:

  import express from 'express';

  const app = express();
  app.use(express.json());

  app.post('/', (req, res) => {
    const channelToken = req.get('X-Goog-Channel-Token');
    const bodyJson = JSON.stringify(req.body);

    console.log(`channel token: ${channelToken}`);
    console.log(`notification body: ${bodyJson}`);

    res.sendStatus(200);
  });

  const port = parseInt(process.env.PORT) || 8080;
  app.listen(port, () => {
    console.log(`helloworld: listening on port ${port}`);
  });

POST 요청으로 전송된 모든 수신 웹훅 알림에 대해 웹훅 알림 JSON 본문과 채널 토큰 값을 출력합니다. 작업이 성공했음을 나타내는 HTTP 코드 200를 반환합니다.

Cloud Run 빠른 시작 튜토리얼이 끝나고 웹훅 애플리케이션을 gcloud run deploy명령어를 사용하고 서비스가 배포되는 URL입니다

서비스 URL은 콘솔에 표시됩니다. 예를 들면 다음과 같습니다.

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

서버 알림 URI입니다. 애플리케이션이 웹훅 알림을 수신하는 위치 Google 애널리틱스.

잠재고객 목록 만들기 및 웹훅 알림 사용 설정

웹훅 알림을 요청하려면 webhookNotification에 다음 값을 지정합니다. 객체:

서버 알림 URI 웹 주소가 포함되어 있습니다.
(선택사항) 임의의 문자열 channelToken 스푸핑되는 메시지를 방지합니다. channelToken 지정 X-Goog-Channel-Token HTTP 헤더에서 웹훅 POST 요청을 처리합니다

다음은 웹훅을 사용하는 샘플 요청입니다.

HTTP 요청

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "webhookNotification": {
    "uri": "https://webhooks-test-abcdef-uc.a.run.app",
    "channelToken": "123456"
  },
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

audienceLists.create 메서드의 응답에는 다음이 포함됩니다. webhookNotification: 지정된 웹훅이 성공적으로 완료되었는지 확인합니다. 5초도 안 되는 시간에 응답했습니다.

다음은 샘플 응답입니다.

HTTP 응답

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged": 51,
    "rowCount": 13956,
    "percentageCompleted": 100,
    "webhookNotification": {
      "uri": "https://webhooks-test-abcdef-uc.a.run.app",
      "channelToken": "123456"
    }
  }
}

웹훅이 응답하지 않거나 잘못된 서비스 URL을 제공하면 오류 메시지가 대신 반환됩니다.

다음은 발생할 수 있는 오류의 예입니다.

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

웹훅 알림 처리

웹훅 서비스에 대한 POST 요청에는 장기 실행 작업 리소스 본문과 sentTimestamp 필드가 있습니다. 전송된 타임스탬프는 요청이 전송된 유닉스 시간(마이크로초 단위) 이 타임스탬프로 다시 재생된 알림을 식별합니다.

요청이 진행되는 동안 하나 또는 두 개의 POST 요청이 웹훅으로 잠재고객 목록 생성:

첫 번째 POST 요청이 즉시 전송되고, 새로 생성된 잠재고객 목록이 CREATING 상태입니다. 첫 번째 요청이 웹훅이 실패하는 경우 audienceLists.create 작업에서 오류를 반환합니다. 웹훅 실패 세부정보를 확인할 수 있습니다
두 번째 POST 요청은 잠재고객 목록이 완료된 후에 전송됩니다. 만들 수 있습니다. 잠재고객 목록이 다음 중 하나에 도달하면 생성이 완료됩니다. ACTIVE 또는 FAILED 상태입니다.

다음은 잠재고객 목록에 대한 첫 번째 알림의 예입니다. CREATING 상태:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"CREATING",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":0,
    "rowCount":0,
    "percentageCompleted":0,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

다음은 잠재고객 목록에 대한 두 번째 알림의 예입니다. ACTIVE 상태:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":68,
    "rowCount":13956,
    "percentageCompleted":100,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

두 번째 알림은 잠재고객 목록이 생성되었으며 audienceLists.query를 사용하여 쿼리 준비 완료 메서드를 사용하여 축소하도록 요청합니다.

audienceLists.create 메서드를 호출한 후 웹훅을 테스트하려면 다음을 실행합니다. 로그를 검사하고 확인하고 모든 애플리케이션의 JSON 본문을 Google 애널리틱스에서 전송하는 알림입니다.