Mit der Merchant Notifications API können Sie Push-Benachrichtigungen zu Änderungen an Kontodaten erhalten. Wenn Sie beispielsweise Benachrichtigungen zu Produktstatusänderungen abonnieren, werden Sie in Echtzeit benachrichtigt, wenn ein Produkt abgelehnt wird. Sie können Benachrichtigungen für alle Ihre untergeordneten Konten oder andere verknüpfte Konten abonnieren.
In diesem Leitfaden finden Sie Beispiele dazu, wie Sie Benachrichtigungen zu Änderungen des Produktstatus verwalten. Sie können diese Beispiele verwenden, um Benachrichtigungen für andere Ereignisse zu verwalten. Ändern Sie dazu den Wert des Felds registeredEvent in Ihren Anfragen. Eine vollständige Liste der Ereignistypen finden Sie in der Merchant Notifications API-Referenz.
Abonnieren
Um Benachrichtigungen zu erhalten, benötigen Sie eine callBackUri. Der Rückruf-URI muss die folgenden Anforderungen erfüllen:
- Muss eine öffentlich zugängliche HTTPS-Adresse mit einem gültigen SSL-Zertifikat sein, das von einer Zertifizierungsstelle signiert wurde.
- Muss HTTP-
POST-Anfragen mit demContent-Type-Header und dem Wertapplication/jsonakzeptieren. - Es muss einer der folgenden Antwortcodes zurückgegeben werden, um zu bestätigen, dass die Benachrichtigung eingegangen ist.
102200201202204
Sie können dieselbe Rückruf-URI für mehrere Abos verwenden. Wir empfehlen, pro erweitertem Konto und pro Ereignistyp einen eindeutigen Rückruf-URI zu verwenden, um die Anzahl der Push-Anfragen an einen einzelnen URI zu minimieren.
Hier ist ein Beispiel für eine Anfrage, um Benachrichtigungen zu Produktstatusänderungen für ein bestimmtes Händlerkonto zu abonnieren. Verwenden Sie die Händler-ID des Kontos, das die Benachrichtigungen erhalten soll, als merchantId in der Anfrage-URL und die Händler-ID des Kontos, für das Benachrichtigungen empfangen werden sollen, als targetMerchantId im Anfragetext. Wenn es sich bei Ihrem Konto um ein eigenständiges Konto ohne verknüpfte Konten handelt und Sie Benachrichtigungen für Ihr eigenes Konto erhalten möchten, verwenden Sie an beiden Stellen Ihre eigene Händler-ID.
POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/TARGETMERCHANT_ID",
"callBackUri": "https://example.com"
}
Bei erfolgreichen Aufrufen wird eine name für dein Abo zurückgegeben, einschließlich einer Abo-ID:
{
"name":"accounts/MERCHANT_ID/notificationsubscriptions/subscriptionId",
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/TARGETMERCHANT_ID",
"callBackUri": "https://example.com"
}
Sie können diesen Code für name bis GET und DELETE einzelne Abos verwenden.
Sie können Benachrichtigungen zu Produktstatusänderungen für alle Ihre verknüpften Konten abonnieren, indem Sie "allManagedAccounts": true anstelle von targetAccount in Ihre Anfrage aufnehmen:
POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com"
}
Wenn du ein bestehendes Abo aktualisieren möchtest, verwende PATCH mit einem update_mask, um die Felder anzugeben, die du aktualisieren möchtest, und die neuen Werte im JSON-Text:
PATCH https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri
{
"callBackUri": "https://my-own-personal-domain.com"
}
Benachrichtigungen decodieren
Nachdem Sie ein Abo erstellt haben, erhalten Sie Benachrichtigungen an die angegebene callBackUri im folgenden Format:
{"message":{"data":"{base64_encoded_string}"}}
Die Benachrichtigungsdaten sind codiert. Sie können die Daten in ein lesbares Textformat decodieren, um sie in Ihrer Implementierung zu verwenden. Hier ist ein Beispiel für einen Spring Boot-Controller, mit dem Sie die codierten Daten verarbeiten können:
@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
}
}
Hier ein Beispiel für ein decodiertes 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",
"eventTime": "2024-03-21T02:43:47.461464Z"
}
Wenn in der Benachrichtigung kein oldValue-Feld vorhanden ist, wurde Ihrem Konto ein neues Produkt hinzugefügt. Wenn das Feld newValue nicht vorhanden ist, wurde das Produkt aus Ihrem Konto gelöscht.
Das Feld expirationTime ist nicht vorhanden, wenn das Produkt gelöscht wurde.
Das Feld reportingContext unterstützt nur die Werte (SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE) aus dem Enum-Wert ReportingContextEnum.
Für das Ereignis „Produktstatusänderung“ haben die Felder oldValue und newValue einen der folgenden Werte : (approved, pending, disapproved, „“).
Das Feld eventTime enthält die Erstellungszeit des Ereignisses. Wenn Sie Nachrichten sortieren möchten, sollten Sie sich auf den Wert in diesem Feld verlassen und nicht auf die Reihenfolge des Empfangs der Nachrichten.
Weitere Informationen finden Sie im Format ProductStatusChangeMessage.
Die Implementierung testen
Hier ist eine Beispielbenachrichtigung, mit der Sie Ihren Rückruf-URI und die Dekodierung testen können:
curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIiwKICAiZXZlbnRUaW1lIjogIjIwMjQtMDMtMjFUMDI6NDM6NDcuNDYxNDY0WiIKfQ=="}}' https://{callBackUri}
Als Antwort auf diesen Aufruf sollte Ihr Callback-URI einen Code für eine erfolgreiche Antwort zurückgeben. Die decodierte Nachricht sollte den folgenden Wert haben:
{
"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"
}