Za pomocą interfejsu Merchant Notifications API możesz otrzymywać powiadomienia push o zmianach danych na koncie. Jeśli na przykład subskrybujesz powiadomienia o zmianie stanu produktu, możesz otrzymywać powiadomienia w czasie rzeczywistym, gdy produkt zostanie odrzucony. Możesz subskrybować powiadomienia dotyczące dowolnego z Twoich podrzędnych kont lub innych połączonych kont.
W tym przewodniku znajdziesz przykłady zarządzania powiadomieniami o zmianach stanu produktu. Korzystając z tych przykładów, możesz zarządzać powiadomieniami o innych zdarzeniach, zmieniając wartość pola registeredEvent w żądaniach. Pełną listę typów zdarzeń znajdziesz w przewodniku po interfejsie Merchant Notifications API.
Subskrybuj
Aby otrzymywać powiadomienia, musisz mieć callBackUri. Adres URI wywołania zwrotnego musi spełniać te wymagania:
- Musi to być publicznie dostępny adres HTTPS z prawidłowym certyfikatem SSL podpisanym przez urząd certyfikacji.
- Musi akceptować żądania HTTP
POSTz nagłówkiemContent-Typei wartościąapplication/json. - Musisz zwrócić jeden z tych kodów odpowiedzi, aby potwierdzić, że powiadomienie zostało odebrane.
102200201202204
Możesz używać tego samego adresu URI wywołania zwrotnego dla wielu subskrypcji. Zalecamy używanie osobnego identyfikatora URI wywołania zwrotnego dla każdego zaawansowanego konta i każdego typu zdarzenia, aby zminimalizować obciążenie żądań push pojedynczym identyfikatorem URI.
Oto przykładowa prośba o subskrypcję powiadomień o zmianach stanu produktu na konkretnym koncie sprzedawcy. W adresie URL żądania użyj identyfikatora sprzedawcy konta, które ma otrzymywać powiadomienia, jako merchantId, a w ciele żądania użyj identyfikatora sprzedawcy konta, na które mają być wysyłane powiadomienia, jako targetMerchantId. Jeśli Twoje konto jest samodzielnym kontem bez połączonych kont i chcesz otrzymywać powiadomienia na swoje konto, użyj własnego identyfikatora sprzedawcy w obu miejscach.
POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/TARGETMERCHANT_ID",
"callBackUri": "https://example.com"
}
Pomyślne wywołania zwracają identyfikator name Twojej subskrypcji, w tym identyfikator subskrypcji:
{
"name":"accounts/MERCHANT_ID/notificationsubscriptions/subscriptionId",
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/TARGETMERCHANT_ID",
"callBackUri": "https://example.com"
}
Możesz użyć tego name do GET i DELETE pojedynczych subskrypcji.
Możesz subskrybować powiadomienia o zmianach stanu usług na wszystkich połączonych kontach, dodając w żądaniu "allManagedAccounts": true zamiast targetAccount:
POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com"
}
Aby zaktualizować istniejący abonament, użyj elementu PATCH z elementem update_mask, aby określić pola, które chcesz zaktualizować, i nowe wartości w ciele obiektu JSON:
PATCH https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri
{
"callBackUri": "https://my-own-personal-domain.com"
}
Dekodowanie powiadomień
Po utworzeniu subskrypcji otrzymasz powiadomienia na wskazany adres callBackUri w takim formacie:
{"message":{"data":"{base64_encoded_string}"}}
Dane powiadomienia są zakodowane. Możesz zdekodować dane do czytelnego formatu tekstowego, aby użyć ich w swojej implementacji. Oto przykładowy kontroler Spring Boot, którego możesz użyć do przetworzenia zakodowanych danych:
@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
}
}
Oto przykład odkodowanego elementu base64_encoded_string:
{
"account": "accounts/TARGETMERCHANT_ID",
"managingAccount": "accounts/MERCHANT_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/TARGETMERCHANT_ID/products/ONLINE~en~US~1234",
"expirationTime": "2024-10-22T02:43:47.461464Z"
}
Jeśli w powiadomieniu nie ma pola oldValue, na Twoim koncie został dodany nowy produkt. Jeśli nie ma pola newValue, oznacza to, że produkt został usunięty z Twojego konta.
Pole reportingContext obsługuje tylko wartości (SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT i YOUTUBE_AFFILIATE) z wartości wyliczenia ReportingContextEnum.
W przypadku zdarzenia zmiany stanu produktu pola oldValue i newValue będą zawierać jedną z tych wartości: approved, pending, disapproved, ``.
Testowanie implementacji
Oto przykładowe powiadomienie, którego możesz użyć do przetestowania wywołania zwrotnego URI i odkodowania:
curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIgp9"}}' https://{callBackUri}
W odpowiedzi na to wywołanie URI wywołania zwrotnego powinien zwrócić kod odpowiedzi. Odkodowana wiadomość powinna mieć tę wartość:
{
"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"
}