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

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

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

웹훅 알림은 Google 애널리틱스 Data API의 고급 기능입니다. 잠재고객 내보내기 기능에 대한 소개는 잠재고객 내보내기 만들기를 참고하세요.

웹훅이 없으면 API를 주기적으로 폴링하여 요청이 완료되는 시점을 확인해야 합니다.

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

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

샘플 서비스가 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

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

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

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

웹훅 알림을 수신할 웹 주소가 포함된 서버 알림 URI입니다.
(선택사항) 스푸핑 메시지로부터 보호하기 위한 임의의 문자열 channelToken입니다. 웹훅 POST 요청의 X-Goog-Channel-Token HTTP 헤더에 channelToken을 지정합니다.

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

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 메서드의 응답에는 지정된 웹훅이 5초 이내에 성공적으로 응답했음을 확인하는 webhookNotification가 포함됩니다.

다음은 샘플 응답입니다.

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 요청의 본문에는 JSON 버전의 장기 실행 작업 리소스와 sentTimestamp 필드가 모두 포함됩니다. 전송된 타임스탬프는 요청이 전송된 Unix 에포크 시간을 마이크로초 단위로 지정합니다. 이 타임스탬프를 사용하여 재생된 알림을 식별할 수 있습니다.

잠재고객 목록을 만드는 동안 하나 또는 두 개의 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 메서드를 호출한 후 웹훅을 테스트하려면 샘플 Cloud Run 웹훅 애플리케이션의 로그를 검사하고 Google 애널리틱스에서 보낸 모든 알림의 JSON 본문을 확인하면 됩니다.