Interfejs API powiadomień sprzedawcy umożliwia otrzymywanie powiadomień push o zmianach w danych konta. 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. Możesz używać tych przykładów do zarządzania powiadomieniami o innych zdarzeniach, zmieniając wartość pola registeredEvent w swoich żądaniach. Pełną listę typów zdarzeń znajdziesz w dokumentacji interfejsu Merchant Notification API.
Subskrybuj
Aby otrzymywać powiadomienia, musisz mieć callBackUri. Identyfikator 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. - Aby potwierdzić otrzymanie powiadomienia, musi być zwracany jeden z poniższych kodów odpowiedzi.
102200201202204
Możesz używać tego samego adresu URI wywołania zwrotnego dla wielu subskrypcji. Zalecamy używanie osobnego identyfikatora URI wywołania zwrotnego na konto i na typ 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. Użyj identyfikatora sprzedawcy konta, na które chcesz otrzymywać powiadomienia, jako identyfikatora merchantId w adresie URL żądania oraz identyfikatora sprzedawcy konta, dla którego chcesz otrzymywać powiadomienia, jako identyfikatora targetMerchantId w treści żądania. 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/merchantId/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/targetMerchantId",
"callBackUri": "https://example.com"
}
Pomyślne wywołania zwracają name dla Twojej subskrypcji, w tym identyfikator subskrypcji:
{
"name":"accounts/merchantId/notificationsubscriptions/subscriptionId",
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/targetMerchantId",
"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/merchantId/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com"
}
Aby zaktualizować istniejącą subskrypcję, użyj polecenia PATCH z parametrem update_mask, aby określić pola, które chcesz zaktualizować, i nowych wartości w treści JSON:
PATCH /notifications/v1beta/accounts/merchantId/notificationsubscriptions/subscriptionId?update_mask=callBackUri
{
"callBackUri": "https://my-own-personal-domain.com"
}
Dekodowanie powiadomień
Gdy utworzysz subskrypcję, będziesz otrzymywać powiadomienia (callBackUri) w tym formacie:
{"message":{"data":"{base64_encoded_string}"}}
Dane powiadomień są zakodowane. Możesz zdekodować dane do czytelnego formatu tekstowego, aby użyć ich w swojej implementacji. Oto przykładowy kontroler wiosennego rozruchu, którego możesz użyć do przetwarzania 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 zdekodowanego elementu base64_encoded_string:
{
"account": "accounts/targetMerchantId",
"managingAccount": "accounts/merchantId",
"resourceType": "PRODUCT",
"attribute": "STATUS",
"changes": [{
"oldValue": "eligible",
"newValue": "disapproved",
"regionCode": "US",
"reportingContext": "SHOPPING_ADS"
}, {
"oldValue": "eligible",
"newValue": "disapproved",
"regionCode": "JP",
"reportingContext": "SHOPPING_ADS"
},{
"oldValue": "eligible",
"newValue": "disapproved",
"regionCode": "GE",
"reportingContext": "SHOPPING_ADS"
}],
"resourceId": "ONLINE~en~US~1234",
"resource": "accounts/targetMerchantId/products/ONLINE~en~US~1234",
"expirationTime": "2024-10-22T02:43:47.461464Z"
}
Jeśli w powiadomieniu nie ma pola oldValue, na Twoje konto 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 i YOUTUBE_CHECKOUT) z wartości wyliczenia ReportingContextEnum.
Testowanie implementacji
Oto przykładowe powiadomienie, które możesz wykorzystać do przetestowania identyfikatora URI wywołania zwrotnego i dekodowania:
curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImVsaWdpYmxlIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIgp9"}}' https://{callBackUri}
W odpowiedzi na to wywołanie identyfikator URI wywołania zwrotnego powinien zwracać kod pomyślnej odpowiedzi. Odkodowany komunikat powinien mieć tę wartość:
{
"account": "accounts/1234",
"managingAccount": "accounts/5678",
"resourceType": "PRODUCT",
"attribute": "STATUS",
"changes": [{
"oldValue": "eligible",
"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"
}