제품 데이터 변경사항에 대한 푸시 알림 받기

Merchant Notifications API를 사용하여 제품 데이터 변경사항에 대한 푸시 알림을 받을 수 있습니다. 예를 들어 제품 상태 변경 알림을 구독하면 제품이 비승인될 때 실시간으로 알림을 받을 수 있습니다. 모든 하위 계정 또는 연결된 다른 계정의 알림을 구독할 수 있습니다.

이 가이드에서는 제품 상태 변경에 대한 알림을 관리하는 방법을 보여주는 예를 제공합니다. 이러한 예를 사용하여 요청에서 registeredEvent 필드의 값을 변경하여 다른 이벤트의 알림을 관리할 수 있습니다. 이벤트 유형의 전체 목록은 Merchant Notifications API 참조를 확인하세요.

구독

알림을 받으려면 callBackUri가 필요합니다. 콜백 URI는 다음 요구사항을 충족해야 합니다.

• 인증 기관에서 서명한 유효한 SSL 인증서가 있는 공개적으로 액세스 가능한 HTTPS 주소여야 합니다.
• Content-Type 헤더와 application/json 값이 있는 HTTP POST 요청을 수락해야 합니다.
• 알림이 수신되었음을 확인하기 위해 다음 응답 코드 중 하나를 반환해야 합니다.
  • 102
  • 200
  • 201
  • 202
  • 204

여러 구독에 동일한 콜백 URI를 사용할 수 있습니다. 단일 URI에 대한 푸시 요청의 부하를 최소화하려면 고급 계정당, 이벤트 유형당 고유한 콜백 URI를 사용하는 것이 좋습니다.

다음은 특정 판매자 계정의 제품 상태 변경에 대한 알림을 구독하는 샘플 요청입니다.

POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/{TARGETACCOUNT_ID}",
  "callBackUri": "https://example.com"
}

다음을 바꿉니다.

• ACCOUNT_ID: 알림을 수신해야 하는 계정의 고유 식별자입니다.
• TARGETACCOUNT_ID: 알림을 수신하려는 계정 의 고유 식별자입니다.

판매자 센터 계정이 연결된 계정이 없는 독립형 계정이고 자체 계정에 대한 알림을 수신하려면 두 변수를 모두 계정 ID로 바꿉니다.

호출이 성공하면 구독 ID를 포함하여 구독의 name 이 반환됩니다.

{
  "name":"accounts/{ACCOUNT_ID}/notificationsubscriptions/subscriptionId",
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/{TARGETACCOUNT_ID}",
  "callBackUri": "https://example.com"
}

이 name을 사용하여 개별 구독을 GET 및 DELETE할 수 있습니다.

요청에 targetAccount 대신 "allManagedAccounts": true를 포함하여 연결된 모든 계정의 제품 상태 변경에 대한 알림을 구독할 수 있습니다.

POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com"
}

기존 구독을 업데이트하려면 update_mask가 있는 PATCH를 사용하여 업데이트할 필드와 HTTP 본문의 새 값을 지정합니다.

PATCH https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri

{
  "callBackUri": "https://my-own-personal-domain.com"
}

알림 디코딩

구독을 만든 후 지정된 callBackUri로 다음 형식의 알림을 받게 됩니다.

{"message":{"data":"{base64_encoded_string}"}}

알림 데이터가 인코딩됩니다. 데이터를 사람이 읽을 수 있는 텍스트 형식으로 디코딩하여 구현에 사용할 수 있습니다. 다음은 인코딩된 데이터를 처리하는 데 사용할 수 있는 샘플 Spring Boot 컨트롤러입니다.

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void doStuff(@RequestBody String message) {
        //wrapped message
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        message = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(message);
        String decodedMessage = new String(decodedBytes);
        // Implement your business logic here
  }
}

다음은 디코딩된 base64_encoded_string의 예입니다.

{
  "account": "accounts/{TARGETACCOUNT_ID}",
  "managingAccount": "accounts/{ACCOUNT_ID}",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/{TARGETACCOUNT_ID}/products/ONLINE~en~US~1234",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}

알림에 oldValue 필드가 없으면 계정에 새 제품이 추가된 것입니다. newValue 필드가 없으면 계정에서 제품이 삭제된 것입니다.

제품이 삭제된 경우 expirationTime 필드가 없습니다.

reportingContext 필드는 열거형 값 ReportingContextEnum의 (SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE, FREE_LISTINGS_UCP_CHECKOUT)만 지원합니다.

제품 상태 변경 이벤트의 경우 oldValue 및 newValue 필드에는 다음 값 중 하나가 있습니다. (approved, pending, disapproved, ``)

eventTime 필드에는 이벤트 자체의 생성 시간이 포함됩니다. 메시지 순서를 지정하려면 해당 필드의 값을 사용하고 메시지 수신 순서를 사용하지 마세요.

자세한 내용은 ProductStatusChangeMessage 형식 을 따르세요.

구현 테스트

다음은 콜백 URI 및 디코딩을 테스트하는 데 사용할 수 있는 샘플 알림입니다.

curl --request POST \
'https://{callBackUri}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--data '{"message":{"data": "ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIiwKICAiZXZlbnRUaW1lIjogIjIwMjQtMDMtMjFUMDI6NDM6NDcuNDYxNDY0WiIKfQ=="}}'

이 호출에 대한 응답으로 콜백 URI는 성공적인 응답 코드를 반환해야 합니다. 디코딩된 메시지에는 다음 값이 있어야 합니다.

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~000000000000",
  "resource": "accounts/1234/products/ONLINE~en~US~000000000000",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}