In diesem Abschnitt wird beschrieben, wie Sie zeitkritische Aktualisierungen Ihrer Inventarelemente an Google senden. Mit der Realtime Updates API können Sie Aktualisierungen pushen und Entitäten in Ihrem Sandbox- oder Produktionsinventar nahezu in Echtzeit löschen.
Diese Funktion ist in erster Linie für Aktualisierungen gedacht, die Sie nicht vorhersehen können, z. B. Notschließungen, das Entfernen von Artikeln aus dem Menü oder die Aktualisierung des Preises eines Menüpunkts, die schnell in der Google-Benutzeroberfläche berücksichtigt werden müssen. Wenn Ihre Änderung nicht sofort berücksichtigt werden muss, können Sie stattdessen die Batchaufnahme verwenden. Echtzeitaktualisierungen werden innerhalb von maximal fünf Minuten verarbeitet.
Vorbereitung
Bevor Sie Echtzeitaktualisierungen implementieren, sind die folgenden Elemente erforderlich:
Die Maps Booking API ist aktiviert:
Rufen Sie in der GCP APIs und Dienste > Bibliothek auf.
Suchen Sie nach „Google Maps Booking API“
Suchen Sie die Sandbox-Instanz („Google Maps Booking API (Dev)“) und klicken Sie auf Aktivieren.
Suchen Sie die Produktionsinstanz („Google Maps Booking API“) und klicken Sie auf Aktivieren.
Es wird ein Dienstkonto mit der Rolle „Bearbeiter“ für Ihr GCP-Projekt erstellt. Weitere Informationen finden Sie unter Kontoeinrichtung.
Produktions- oder Sandbox-Datenfeeds werden gehostet und aufgenommen. Weitere Informationen finden Sie unter Batchaufnahme.
Für die API-Authentifizierung wird empfohlen, die Google-Clientbibliothek in der Sprache Ihrer Wahl zu installieren. Verwenden Sie „https://www.googleapis.com/auth/mapsbooking“ als OAuth-Bereich. In den folgenden Codebeispielen werden diese Bibliotheken verwendet. Andernfalls müssen Sie den Token-Austausch manuell vornehmen, wie im Hilfeartikel Über OAuth 2.0 auf Google APIs zugreifen beschrieben.
Übersicht
Die Echtzeitaktualisierungs-API unterstützt zwei Arten von Vorgängen. Der erste Vorgang ist „upsert“, um vorhandene Entitäten zu aktualisieren. Der zweite Vorgang ist „Löschen“, um Entitäten aus Ihrem Inventar zu entfernen. Beide Vorgänge werden auf eine Reihe von Entitäten angewendet, die im Anfragetext aufgeführt sind. Sie können bis zu 1.000 Entitäten in einem einzigen API-Aufruf aktualisieren. Die API nimmt alle eingehenden Anfragen an und stellt sie zur weiteren Verarbeitung in eine Warteschlange.
Daher werden RTU-Anfragen asynchron verarbeitet.
Die API für Echtzeitaktualisierungen kann in zwei Umgebungen verwendet werden: Sandbox und Produktion.
Die Sandbox-Umgebung wird zum Testen der API-Anfragen und die Produktionsumgebung zum Aktualisieren der Inhalte verwendet, die für End-to-End-Nutzer der Bestellung sichtbar sind. Hostnamen beider Umgebungen:
Sandbox – partnerdev-mapsbooking.googleapis.com
Produktion – mapsbooking.googleapis.com
Endpunkte
Die API für Echtzeitaktualisierungen stellt zwei Endpunkte bereit, um eingehende Anfragen für Bestandsaktualisierungen zu verarbeiten:
Der Parameter PARTNER_ID ist im Actions Center auf der Seite Konto und Nutzer als Partner-ID zu finden (siehe Screenshot unten).
Angenommen, 10000001 ist der Wert für PARTNER_ID im Screenshot oben. Die vollständigen URLs zum Senden von API-Anfragen in der Sandbox und in der Produktion sehen dann so aus wie in den Beispielen unten.
# Production UPSERT
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/owg.v2/record:batchPush
# Production DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/owg.v2/record:batchDelete
Entitäten aktualisieren
Wenn du Entitäten in deinem Inventar aktualisieren möchtest, verwende den EndpunktUPSERT und sende HTTP POST-Anfragen. Jede POST-Anfrage muss den Parameter PARTNER_ID sowie die JSON-Nutzlast mit den strukturierten Daten eines beliebigen Entitätstyps enthalten, der im Inventarschema aufgeführt ist.
Nutzlast der Upsert-Anfrage
Der Anfragetext ist ein JSON-Objekt mit einer Liste von Einträgen. Jeder Datensatz entspricht einer zu aktualisierenden Entität. Es besteht aus dem Feld data_record mit der Base64-codierten Entitätsnutzlast und dem Feld generation_timestamp, das die Zeit der Entitätsaktualisierung angibt:
BASE_64_ENCODED_ENTITY: Der base64-codierte JSON-String der Entität. Die decodierte JSON-Entität sollte dieselbe Struktur wie in der Feedspezifikation haben, z. B.:
{"@type":"MenuSection","name":"My Updated Menu Section","menuId":{"@id":"10824","displayOrder":1},"@id":"853705"}
UPDATE_TIMESTAMP: Geben Sie den Zeitstempel an, zu dem die Entität in Ihren Backend-Systemen generiert wurde. Anhand dieses Zeitstempels wird die korrekte Reihenfolge der Inventaraktualisierungen sichergestellt. Wenn dieses Feld nicht enthalten ist, wird es auf die Uhrzeit festgelegt, zu der Google die Anfrage erhält. Wenn eine Entität über eine batchPush-Anfrage aktualisiert wird, wird das Feld generation_timestamp für die Entitätsversionierung verwendet. Sehen Sie sich das erwartete Format der Zeitwerte im relationalen Inventarschema an.
Jede Anfrage für Echtzeitaktualisierungen muss die folgenden Bedingungen erfüllen:
Der Payload-Body darf nicht größer als 5 MB sein. Ähnlich wie bei Batchfeeds empfehlen wir, Lücken zu entfernen, damit mehr Daten passen.
Eine batchPush-Anfrage kann bis zu 1.000 Entitäten enthalten.
Beispiele
Beispiel 1: Restaurant aktualisieren
Angenommen, Sie müssen dringend die Telefonnummer eines Restaurants aktualisieren. Ihre Aktualisierung enthält die JSON-Datei für das gesamte Restaurant.
Angenommen, Sie haben einen Batchfeed, der so aussieht:
Verwenden Sie keine Echtzeitaktualisierungen, um neue Entitäten hinzuzufügen, da dies zu Dateninkonsistenzen führen kann. Verwenden Sie stattdessen den Batchfeed-Prozess, wie für die Batchaufnahme beschrieben.
Entitäten löschen
Wenn Sie Entitäten aus Ihrem Inventar löschen möchten, verwenden Sie den DELETE-Endpunkt und senden Sie HTTP-POST-Anfragen. Jede POST-Anfrage muss den Parameter PARTNER_ID sowie die JSON-Nutzlast mit der Kennung einer Entität in Ihrem Inventar enthalten.
Löschen der Anfragenutzlast
Der Text einer Löschanfrage ist ähnlich aufgebaut wie der einer Aktualisierungsanfrage.
Außerdem enthält es eine Liste von Einträgen mit data_record- und delete_time-Feldern:
BASE_64_ENCODED_REFERENCE: Der Base64-codierte JSON-String der Referenz auf die Entität, die entfernt wird. Eine Referenz besteht nur aus dem Entitätstyp und der Kennung, z. B. eine JSON-Darstellung einer Referenz auf einen MenuSection:
{"@type":"MenuSection","@id":"853705"}
DELETE_TIMESTAMP: Geben Sie den Zeitstempel an, zu dem die Entität in Ihrem Backend-System gelöscht wurde. Anhand dieses Zeitstempels wird die Reihenfolge bestimmt, in der ein Löschen auf das Inventar angewendet wird.
Eine batchDelete-Anfrage kann bis zu 1.000 Entitäten enthalten.
Beispiele
Beispiel 1: Entfernen von zwei MenuItem-Entitäten
Wenn Sie zwei Menüpunkte in einem einzigen API-Aufruf entfernen möchten, sieht die HTTP-POST-Anfrage so aus:
Angenommen, Sie möchten ein Restaurant im Batchfeed löschen.
Sie müssen nur die Restaurantentität löschen. Löschen Sie keine untergeordneten Entitäten wie Dienstleistungen und Menüs, da sie automatisch entfernt werden.
Beispielanfrage zum Löschen einer Restaurantentität mit der ID https://www.provider.com/restaurant/12345:
Es gibt zwei Arten von Validierungen, die bei den API-Aufrufen für Echtzeitaktualisierungen ausgeführt werden:
Auf Anfrageebene: Bei diesen Validierungen wird geprüft, ob die Nutzlast dem Schema Upsert oder Delete entspricht und jede data_record sowohl die Felder @id als auch @type enthält.
Diese Prüfungen sind synchron und die Ergebnisse werden im API-Antwortkörper zurückgegeben. Ein Antwortcode 200 und ein leerer JSON-Textkörper {} bedeuten, dass diese Prüfungen bestanden haben und die Entitäten in dieser Anfrage zur Verarbeitung in die Warteschlange gestellt wurden. Ein Antwortcode, der sich von 200 unterscheidet, bedeutet, dass eine oder mehrere dieser Validierungen fehlgeschlagen sind und die gesamte Anfrage abgelehnt wurde (einschließlich aller Entitäten in der Nutzlast). Wenn bei einer data_record beispielsweise ein @type fehlt, wird die folgende Fehlerantwort zurückgegeben:
{"error":{"code":400,"message":"Record:{\"@id\":\"2717/86853/DELIVERY\",\"applicableServiceType\":[\"DELIVERY\",\"TAKEOUT\"],\"menuId\":[{\"@id\":\"2717/DELIVERY\",\"displayOrder\":1},{\"@id\":\"2717/TAKEOUT\",\"displayOrder\":2}],\"name\":\"Salad\",\"offeredById\":[\"2717\"]} has following errors: \nThe entity type could not be extracted from the entity value.\n","status":"INVALID_ARGUMENT","details":[{"@type":"type.googleapis.com/google.rpc.DebugInfo","detail":"[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:{\"@id\":\"2717/86853/DELIVERY\",\"applicableServiceType\":[\"DELIVERY\",\"TAKEOUT\"],\"menuId\":[{\"@id\":\"2717/DELIVERY\",\"displayOrder\":1},{\"@id\":\"2717/TAKEOUT\",\"displayOrder\":2}],\"name\":\"Salad\",\"offeredById\":[\"2717\"]} has following errors: \nThe entity type could not be extracted from the entity value.\n [google.rpc.error_details_ext] { message: \"Record:{\\\"@id\\\":\\\"2717/86853/DELIVERY\\\",\\\"applicableServiceType\\\":[\\\"DELIVERY\\\",\\\"TAKEOUT\\\"],\\\"menuId\\\":[{\\\"@id\\\":\\\"2717/DELIVERY\\\",\\\"displayOrder\\\":1},{\\\"@id\\\":\\\"2717/TAKEOUT\\\",\\\"displayOrder\\\":2}],\\\"name\\\":\\\"Salad\\\",\\\"offeredById\\\":[\\\"2717\\\"]} has following errors: \\nThe entity type could not be extracted from the entity value.\\n\" }"}]}}
Entitätsebene: Jede Entität in der Nutzlast wird anhand des relationalen Schemas validiert.
Probleme, die in dieser Validierungsphase auftreten, werden nicht in der API-Antwort gemeldet. Sie werden nur im Dashboard RTU-Berichte erfasst.
API-Kontingente
Für Echtzeit-API-Aktualisierungen ist ein Kontingent von 1.500 Anfragen pro 60 Sekunden zugewiesen. Das entspricht durchschnittlich 25 Anfragen pro Sekunde. Wird das Kontingent überschritten, siehst du folgenden Fehlermeldung:
Wiederhole den Aufruf in diesem Fall in exponentiell größeren Abständen, bis er erfolgreich ist. Wenn Sie das Kontingent regelmäßig ausschöpfen, sollten Sie in einer API-Anfrage mehr Entitäten angeben. Sie können bis zu 1.000 Entitäten in einem API-Aufruf angeben.
Codebeispiele
Nachfolgend finden Sie einige Beispiele für die Verwendung der Echtzeitaktualisierungs-API in verschiedenen Sprachen. In diesen Beispielen werden die Google Auth-Bibliotheken verwendet, um sich mit einer Dienstkonto-Schlüsseldatei zu authentifizieren, die bei der Kontoeinrichtung generiert wurde.
Informationen zu alternativen Lösungen finden Sie unter OAuth 2.0 für Server-zu-Server-Anwendungen verwenden.
Sie können das Schema verwenden, das unter Clientbibliotheken generieren verfügbar ist, um Quellcode für die Inventar- und Echtzeitaktualisierungsobjekttypen zu generieren.
/* Sample code for Real-time update batchPush implementation. * * Required libraries: * - google-auth-library */const{JWT}=require('google-auth-library');// ACTION REQUIRED: Change this to the path of the service account client secret// file downloaded from the Google Cloud Console.constserviceAccountJson=require('./service-account.json');// ACTION REQUIRED: Change this to your Partner ID received from Google.// The Partner ID is available on the Partner Portal.constPARTNER_ID=1234;constHOST={prod:'https://mapsbooking.googleapis.com',sandbox:'https://partnerdev-mapsbooking.googleapis.com'};// ACTION REQUIRED: Change to 'prod' for productionconstENV='sandbox';// Feed name for Order with Google including the version.constFEED_NAME='owg.v2';// Endpoint urlconsturl=`${HOST[ENV]}/v1alpha/inventory/partners/${PARTNER_ID}/feeds/${FEED_NAME}/record:batchPush`;/** * Send a Real-time update request to update/insert entities */asyncfunctionbatchUpsert(entities){/** * Sign JWT token using private key from service account secret file * provided. The client can be created without providing a service account * secret file by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-nodejs */constclient=newJWT({email:serviceAccountJson.client_email,key:serviceAccountJson.private_key,scopes:['https://www.googleapis.com/auth/mapsbooking'],});constrequest={records:toPushRecords(entities)};constbody=JSON.stringify(request);try{constresponse=awaitclient.request({method:'POST',url,data:body,headers:{'Content-Type':'application/json'}});console.log('request body:',body);console.log('response status:',response.status);console.log('response data:',response.data);// successful response returns '{}'}catch(error){console.log('error:',error);}}/** * Maps array of entities to records for batch push requests */consttoPushRecords=(entities)=>{returnentities.map((entity)=>{// Using dateModified to set generation_timestamp. Defaulting to the// current timestamp for records that do not have dateModified.constgeneration_timestamp=entity.dateModified?entity.dateModified:newDate().toISOString();return{data_record:btoa(JSON.stringify(entity)),generation_timestamp};});};// Call batchUpsert with example entities. dateModified is optional and is// used to hold the actual timestamp when the entity was updated/created.batchUpsert([{'@type':'MenuItemOffer','@id':'6680261','menuItemId':'18931508','price':15.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'},{'@type':'MenuItemOffer','@id':'6680262','menuItemId':'18931509','price':25.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'}]);
"""Sample code for the Real-time update batchPush implementation."""# Required libraries:# - google-authimportbase64importdatetimeimportjsonfromgoogle.auth.transport.requestsimportAuthorizedSessionfromgoogle.oauth2importservice_account# ACTION REQUIRED: Change this to the Partner ID received from Google.# Partner ID is available on the Partner Portal.# https://partnerdash.google.com/apps/reservewithgoogle_PARTNER_ID='1234'# ACTION REQUIRED: Change this to the path of the service account client secret# file downloaded from the Google Cloud Console._SERVICE_ACCOUNT_KEY_JSON_FILE='service-account-creds.json'_HOST_MAP={'sandbox':'https://partnerdev-mapsbooking.googleapis.com','prod':'https://mapsbooking.googleapis.com'}# ACTION REQUIRED: Change to 'prod' for production_ENV='sandbox'# Feed name for Order with Google including the version._FEED_NAME='owg.v2'_ENDPOINT='{}/v1alpha/inventory/partners/{}/feeds/{}/record:batchPush'.format(_HOST_MAP[_ENV],_PARTNER_ID,_FEED_NAME)defbatch_upsert(entities):"""Makes a batchPush request using the Real-time updates REST service. Args: entities: The list of entity objects to update or add. """# Creates credentials by providing a json file. Credentials can also be# provided by implementing Application Default Credentials.# https://googleapis.dev/python/google-auth/latest/user-guide.htmlcredentials=service_account.Credentials.from_service_account_file(_SERVICE_ACCOUNT_KEY_JSON_FILE,scopes=['https://www.googleapis.com/auth/mapsbooking'])authorized_session=AuthorizedSession(credentials)# JSON request objectbatch_request={'records':[create_push_record(x)forxinentities]}response=authorized_session.post(_ENDPOINT,json=batch_request)print('request body:',json.dumps(batch_request))print('response status:',response.status_code)print('response data:',response.text)# successful response returns '{}'defcreate_push_record(entity):"""Creates a record from an entity for batchPush requests. Args: entity: The entity object to create the record from. Returns: The constructed record for the batchPush request payload. """data_bytes=json.dumps(entity).encode('utf-8')base64_bytes=base64.b64encode(data_bytes)# Using dateModified to set generation_timestamp. Defaulting to the# current timestamp for records that do not have dateModified.generation_timestamp=entity.dateModifiedif'dateModified'inentityelsedatetime.datetime.now().strftime('%Y-%m-%dT%H:%M:%S.%fZ')return{'generation_timestamp':generation_timestamp,'data_record':base64_bytes.decode('utf-8')}# Call batch_upsert with example entities. dateModified is optional and is# used to hold the actual timestamp when the entity was updated/created.batch_upsert([{'@type':'MenuItemOffer','@id':'6680261','menuItemId':'18931508','price':15.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'},{'@type':'MenuItemOffer','@id':'6680262','menuItemId':'18931509','price':25.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'}])
Die Client-Quellcodemodelle in den Paketen rtusamples.inventory und rtusamples.realtime wurden mithilfe der Schritte unter Clientbibliotheken generieren erstellt.
/* * Required Libraries: * - JDK >= 11 * - google-auth-library-oauth2-http */packagertusamples;importcom.fasterxml.jackson.core.JsonProcessingException;importcom.fasterxml.jackson.databind.ObjectMapper;importcom.google.auth.oauth2.AccessToken;importcom.google.auth.oauth2.GoogleCredentials;importjava.io.FileInputStream;importjava.io.IOException;importjava.net.URI;importjava.net.http.HttpClient;importjava.net.http.HttpRequest;importjava.net.http.HttpRequest.BodyPublishers;importjava.net.http.HttpResponse;importjava.net.http.HttpResponse.BodyHandlers;importjava.nio.charset.Charset;importjava.time.Clock;importjava.time.OffsetDateTime;importjava.time.format.DateTimeFormatter;importjava.util.ArrayList;importjava.util.Arrays;importjava.util.Base64;importjava.util.List;importjava.util.Optional;importjava.util.stream.Collectors;importrtusamples.inventory.MenuItemOffer;importrtusamples.inventory.MenuItemOfferType;importrtusamples.inventory.ServiceTypeElement;importrtusamples.realtime.BatchPushGenericRecordRequest;importrtusamples.realtime.GenericRecord;/** Sample code for Real-time update batchPush implementation. */publicfinalclassBasicPush{// ACTION REQUIRED: Change this to your Partner ID received from Google. The Partner ID is// available on the Partner Portal.privatestaticfinallongPARTNER_ID=12345678;// ACTION REQUIRED: Change this to the path of the service account client secret file downloaded// from the Google Cloud Console.privatestaticfinalStringJSON_KEY_FULL_PATH="<path to your JSON credentials>/credentials.json";// ACTION REQUIRED: Change this to the endpoint that is needed.privatestaticfinalStringENDPOINT=// "https://partnerdev-mapsbooking.googleapis.com"; // for sandbox"https://mapsbooking.googleapis.com";// for prod// Feed name for Order with Google including the version.privatestaticfinalStringFEED_NAME="owg.v2";privatestaticfinalObjectMapperobjectMapper=newObjectMapper();privatestaticfinalDateTimeFormatterTIMESTAMP_FORMATTER=DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'");privatestaticfinalCharsetUTF_8=Charset.forName("UTF-8");publicstaticvoidmain(String[]args)throwsException{/** * Create credentials from service account secret file. Alternatively, the credentials can be * created by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-java */// GoogleCredentials sourceCredentials =// GoogleCredentials.getApplicationDefault()// .createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// ImpersonatedCredentials credentials =// ImpersonatedCredentials.create(// sourceCredentials,// "fo-test@projectname.iam.gserviceaccount.com",// null,// Arrays.asList("https://www.googleapis.com/auth/mapsbooking"),// 300);GoogleCredentialscredentials=GoogleCredentials.fromStream(newFileInputStream(JSON_KEY_FULL_PATH)).createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// Create example MenuItemOffer entities, dateModified is optional and is used to hold// the actual timestamp when the entity was updated/created.MenuItemOffermenuItemOfferPizza=newMenuItemOffer();menuItemOfferPizza.setID("6680261");menuItemOfferPizza.setType(MenuItemOfferType.MENU_ITEM_OFFER);menuItemOfferPizza.setMenuItemID("18931508");menuItemOfferPizza.setPrice(15.5);menuItemOfferPizza.setPriceCurrency("USD");menuItemOfferPizza.setApplicableServiceType(newServiceTypeElement[]{ServiceTypeElement.TAKEOUT,ServiceTypeElement.DELIVERY});menuItemOfferPizza.setInventoryLevel(0.0);menuItemOfferPizza.setDateModified("2022-10-07T13:00:00.000Z");MenuItemOffermenuItemOfferSalad=newMenuItemOffer();menuItemOfferSalad.setID("6680262");menuItemOfferSalad.setType(MenuItemOfferType.MENU_ITEM_OFFER);menuItemOfferSalad.setMenuItemID("18931509");menuItemOfferSalad.setPrice(25.5);menuItemOfferSalad.setPriceCurrency("USD");menuItemOfferSalad.setApplicableServiceType(newServiceTypeElement[]{ServiceTypeElement.TAKEOUT,ServiceTypeElement.DELIVERY});menuItemOfferSalad.setInventoryLevel(0.0);menuItemOfferSalad.setDateModified("2022-10-07T13:00:00.000Z");// Example array of MenuItemOffer entities to update.List<MenuItemOffer>menuItemOffers=Arrays.asList(menuItemOfferPizza,menuItemOfferSalad);// Create list of GenericRecord from menuItemOffers.List<GenericRecord>menuItemOfferGenericRecords=menuItemOffers.stream().map((menuItemOffer)->
toBatchPushRecord(menuItemOffer,menuItemOffer.getDateModified())).collect(Collectors.toList());// List of records to be updated/created.List<GenericRecord>recordsToBeUpdated=newArrayList<>();// Add list of menuItemOffer generic records.recordsToBeUpdated.addAll(menuItemOfferGenericRecords);// Request object that contains all records.BatchPushGenericRecordRequestbatchPushRequest=newBatchPushGenericRecordRequest();batchPushRequest.setRecords(recordsToBeUpdated.toArray(newGenericRecord[0]));// Execute batchPush request.BasicPushbasicPush=newBasicPush();basicPush.batchPush(batchPushRequest,credentials);}publicvoidbatchPush(BatchPushGenericRecordRequestbatchPushRequest,GoogleCredentialscredentials)throwsIOException{credentials.refreshIfExpired();AccessTokentoken=credentials.getAccessToken();StringrequestBody=objectMapper.writeValueAsString(batchPushRequest);HttpClientclient=HttpClient.newHttpClient();HttpRequestrequest=HttpRequest.newBuilder().uri(URI.create(String.format("%s/v1alpha/inventory/partners/%s/feeds/%s/record:batchPush",ENDPOINT,PARTNER_ID,FEED_NAME))).header("Content-Type","application/json").header("Authorization",String.format("Bearer %s",token.getTokenValue())).POST(BodyPublishers.ofString(requestBody)).build();HttpResponse<String>response=null;try{response=client.send(request,BodyHandlers.ofString());System.out.println("Request body:"+requestBody);System.out.println("Response status:"+response.statusCode());System.out.println("Response body:"+response.body());}catch(IOException|InterruptedExceptione){e.printStackTrace();}}publicstatic<T>GenericRecordtoBatchPushRecord(Tentity,StringdateModified){GenericRecordgenericRecord=newGenericRecord();try{Stringjson=objectMapper.writeValueAsString(entity);genericRecord.setDataRecord(Base64.getEncoder().encodeToString(json.getBytes(UTF_8)));// Using dateModified to set generation_timestamp. Defaulting to the// current timestamp for records that do not have dateModified.StringgenerationTimestamp=Optional.ofNullable(dateModified).orElse(OffsetDateTime.now(Clock.systemUTC()).format(TIMESTAMP_FORMATTER));genericRecord.setGenerationTimestamp(generationTimestamp);}catch(JsonProcessingExceptione){System.out.println(e.getMessage());}returngenericRecord;}}
/* Sample code for Real-time update batchDelete implementation. * * Required libraries: * - google-auth-library */const{JWT}=require('google-auth-library');// ACTION REQUIRED: Change this to the path of the service account client secret// file downloaded from the Google Cloud Console.constserviceAccountJson=require('./service-account.json');// ACTION REQUIRED: Change this to your Partner ID received from Google.// The Partner ID is available on the Partner Portal.constPARTNER_ID=1234;constHOST={prod:'https://mapsbooking.googleapis.com',sandbox:'https://partnerdev-mapsbooking.googleapis.com'};// ACTION REQUIRED: Change to 'prod' for productionconstENV='sandbox';// Feed name for Order with Google including the version.constFEED_NAME='owg.v2';// Endpoint urlconsturl=`${HOST[ENV]}/v1alpha/inventory/partners/${PARTNER_ID}/feeds/${FEED_NAME}/record:batchDelete`;/** * Send a Real-time update request to delete entities */asyncfunctionbatchDelete(entities){try{/** * Sign JWT token using private key from service account secret file * provided. The client can be created without providing a service account * secret file by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-nodejs */constclient=newJWT({email:serviceAccountJson.client_email,key:serviceAccountJson.private_key,scopes:['https://www.googleapis.com/auth/mapsbooking'],});constrequest={records:toDeleteRecords(entities)};constbody=JSON.stringify(request);try{constresponse=awaitclient.request({method:'POST',url,data:body,headers:{'Content-Type':'application/json'}});console.log('request body:',body);console.log('response status:',response.status);console.log('response data:',response.data);// successful response returns '{}'}catch(error){console.log('error:',error);}}/** * Maps array of entities to records for batch delete requests */consttoDeleteRecords=(entities)=>{returnentities.map((entity)=>{// Using dateModified to set delete_time. Defaulting to the current// timestamp for records that do not have dateModified.constdelete_time=entity.dateModified?entity.dateModified:newDate().toISOString();return{data_record:btoa(JSON.stringify(entity)),delete_time};});};// Call batchDelete with example entities. dateModified is optional and is// used to hold the actual timestamp when the entity was deleted.batchDelete([{'@type':'Menu','@id':'853706','dateModified':'2022-06-19T15:43:50.970Z'},{'@type':'Menu','@id':'853705','dateModified':'2022-06-19T15:13:00.280Z'}]);
"""Sample code for the Real-time update batchDelete implementation."""# Required libraries:# - google-authimportbase64importdatetimeimportjsonfromgoogle.auth.transport.requestsimportAuthorizedSessionfromgoogle.oauth2importservice_account# ACTION REQUIRED: Change this to the Partner ID received from Google.# Partner ID is available on the Partner Portal.# https://partnerdash.google.com/apps/reservewithgoogle_PARTNER_ID='1234'# ACTION REQUIRED: Change this to the path of the service account client secret# file downloaded from the Google Cloud Console._SERVICE_ACCOUNT_KEY_JSON_FILE='service-account-creds.json'_HOST_MAP={'sandbox':'https://partnerdev-mapsbooking.googleapis.com','prod':'https://mapsbooking.googleapis.com'}# ACTION REQUIRED: Change to 'prod' for production_ENV='sandbox'# Feed name for Order with Google including the version._FEED_NAME='owg.v2'_ENDPOINT='{}/v1alpha/inventory/partners/{}/feeds/{}/record:batchDelete'.format(_HOST_MAP[_ENV],_PARTNER_ID,_FEED_NAME)defbatch_delete(entities):"""Makes a batch delete request using the Real-time updates REST service. Args: entities: The list of entity objects to delete. """# Creates credentials by providing a json file. Credentials can also be# provided by implementing Application Default Credentials.# https://googleapis.dev/python/google-auth/latest/user-guide.htmlcredentials=service_account.Credentials.from_service_account_file(_SERVICE_ACCOUNT_KEY_JSON_FILE,scopes=['https://www.googleapis.com/auth/mapsbooking'])authorized_session=AuthorizedSession(credentials)# JSON request objectbatch_request={'records':[create_delete_record(x)forxinentities]}response=authorized_session.post(_ENDPOINT,json=batch_request)print('request body:',json.dumps(batch_request))print('response status:',response.status_code)print('response data:',response.text)# successful response returns '{}'defcreate_delete_record(entity):"""Creates a record from an entity for batchDelete requests. Args: entity: The entity object to create the record from. Returns: The constructed record for the batchDelete request payload. """data_bytes=json.dumps(entity).encode('utf-8')base64_bytes=base64.b64encode(data_bytes)# Using dateModified to set delete_time. Defaulting to the current# timestamp for records that do not have dateModified.delete_time=entity.dateModifiedif'dateModified'inentityelsedatetime.datetime.now().strftime('%Y-%m-%dT%H:%M:%S.%fZ')return{'delete_time':delete_time,'data_record':base64_bytes.decode('utf-8')}# Call batch_delete with example entities. dateModified is optional and is# used to hold the actual timestamp when the entity was deleted.batch_delete([{'@type':'Menu','@id':'853706','dateModified':'2022-06-19T13:10:00.000Z'},{'@type':'Menu','@id':'853705','dateModified':'2022-06-19T13:30:10.000Z'}])
Die Client-Quellcodemodelle in den Paketen rtusamples.inventory und rtusamples.realtime wurden mithilfe der Schritte unter Clientbibliotheken generieren erstellt.
/* * Required Libraries: * - JDK >= 11 * - google-auth-library-oauth2-http */packagertusamples;importcom.fasterxml.jackson.core.JsonProcessingException;importcom.fasterxml.jackson.databind.ObjectMapper;importcom.google.auth.oauth2.AccessToken;importcom.google.auth.oauth2.GoogleCredentials;importjava.io.FileInputStream;importjava.io.IOException;importjava.net.URI;importjava.net.http.HttpClient;importjava.net.http.HttpRequest;importjava.net.http.HttpRequest.BodyPublishers;importjava.net.http.HttpResponse;importjava.net.http.HttpResponse.BodyHandlers;importjava.nio.charset.Charset;importjava.time.Clock;importjava.time.OffsetDateTime;importjava.time.format.DateTimeFormatter;importjava.util.ArrayList;importjava.util.Arrays;importjava.util.Base64;importjava.util.List;importjava.util.Optional;importjava.util.stream.Collectors;importrtusamples.inventory.Menu;importrtusamples.inventory.MenuType;importrtusamples.realtime.BatchDeleteGenericRecordsRequest;importrtusamples.realtime.GenericDeleteRecord;/** Sample code for the Real-time update batchDelete implementation. */publicfinalclassBasicDelete{// ACTION REQUIRED: Change this to your Partner ID received from Google. The Partner ID is// available on the Partner Portal.privatestaticfinallongPARTNER_ID=123456789;// ACTION REQUIRED: Change this to the path of the service account client secret file downloaded// from the Google Cloud Console.privatestaticfinalStringJSON_KEY_FULL_PATH="<path to your JSON credentials>/credentials.json";// ACTION REQUIRED: Change this to the endpoint that is needed.privatestaticfinalStringENDPOINT="https://partnerdev-mapsbooking.googleapis.com";// for sandbox// "https://mapsbooking.googleapis.com" // for prod// Feed name for Order with Google including the version.privatestaticfinalStringFEED_NAME="owg.v2";privatestaticfinalObjectMapperobjectMapper=newObjectMapper();privatestaticfinalDateTimeFormatterTIMESTAMP_FORMATTER=DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'");privatestaticfinalCharsetUTF_8=Charset.forName("UTF-8");publicstaticvoidmain(String[]args)throwsException{/** * Create credentials from service account secret file. Alternatively, the credentials can be * created by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-java */// GoogleCredentials sourceCredentials =// GoogleCredentials.getApplicationDefault()// .createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// ImpersonatedCredentials credentials =// ImpersonatedCredentials.create(// sourceCredentials,// "fo-test@projectname.iam.gserviceaccount.com",// null,// Arrays.asList("https://www.googleapis.com/auth/mapsbooking"),// 300);GoogleCredentialscredentials=GoogleCredentials.fromStream(newFileInputStream(JSON_KEY_FULL_PATH)).createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// Create example Menu entities, dateModified is optional and is used to hold// the actual timestamp when the entity was deleted.MenumenuLunch=newMenu();menuLunch.setID("853705");menuLunch.setType(MenuType.MENU);menuLunch.setDateModified("2022-09-19T13:10:00.000Z");MenumenuDinner=newMenu();menuDinner.setID("853706");menuDinner.setType(MenuType.MENU);menuDinner.setDateModified("2022-09-19T13:13:10.000Z");// Example array of Menu entities to update.List<Menu>menus=Arrays.asList(menuLunch,menuDinner);// Create list of GenericDeleteRecord from menus.List<GenericDeleteRecord>menuGenericDeleteRecords=menus.stream().map((menu)->toBatchDeleteRecord(menu,menu.getDateModified())).collect(Collectors.toList());// List of records to be deleted.List<GenericDeleteRecord>recordsToBeDeleted=newArrayList<>();// Add list of menu generic records.recordsToBeDeleted.addAll(menuGenericDeleteRecords);// Request object that contains all records.BatchDeleteGenericRecordsRequestbatchDeleteRequest=newBatchDeleteGenericRecordsRequest();batchDeleteRequest.setRecords(recordsToBeDeleted.toArray(newGenericDeleteRecord[0]));// Execute batchDelete request.BasicDeletebasicDelete=newBasicDelete();basicDelete.batchDelete(batchDeleteRequest,credentials);}publicvoidbatchDelete(BatchDeleteGenericRecordsRequestbatchDeleteRequest,GoogleCredentialscredentials)throwsIOException{credentials.refreshIfExpired();AccessTokentoken=credentials.getAccessToken();StringrequestBody=objectMapper.writeValueAsString(batchDeleteRequest);HttpClientclient=HttpClient.newHttpClient();HttpRequestrequest=HttpRequest.newBuilder().uri(URI.create(String.format("%s/v1alpha/inventory/partners/%s/feeds/%s/record:batchDelete",ENDPOINT,PARTNER_ID,FEED_NAME))).header("Content-Type","application/json").header("Authorization",String.format("Bearer %s",token.getTokenValue())).POST(BodyPublishers.ofString(requestBody)).build();HttpResponse<String>response=null;try{response=client.send(request,BodyHandlers.ofString());System.out.println("Request body:"+requestBody);System.out.println("Response status:"+response.statusCode());System.out.println("Response body:"+response.body());}catch(IOException|InterruptedExceptione){e.printStackTrace();}}publicstatic<T>GenericDeleteRecordtoBatchDeleteRecord(Tentity,StringdateModified){GenericDeleteRecordgenericRecord=newGenericDeleteRecord();try{Stringjson=objectMapper.writeValueAsString(entity);genericRecord.setDataRecord(Base64.getEncoder().encodeToString(json.getBytes(UTF_8)));// Using dateModified to set delete_time. Defaulting to the current// timestamp for records that do not have dateModified.StringdeleteTime=Optional.ofNullable(dateModified).orElse(OffsetDateTime.now(Clock.systemUTC()).format(TIMESTAMP_FORMATTER));genericRecord.setDeleteTime(deleteTime);}catch(JsonProcessingExceptione){System.out.println(e.getMessage());}returngenericRecord;}}
Anwendungsfälle
Die folgenden Anwendungsfälle sind Beispiele für Echtzeitaktualisierungen, Batchfeed-Aktualisierungen und den allgemeinen Inhalt im API-Aufruf:
Szenario
Zu aktualisierende Entität
Beschreibung und Auswirkungen
Dienst deaktivieren
Service
Sie müssen einen Dienst aus unvorhergesehenen Gründen deaktivieren.
Echtzeitaktualisierungen:Aktualisieren Sie die betreffende Service-Entität, indem Sie das Attribut isDisabled auf true festlegen. Lassen Sie die anderen Attribute unverändert.
Vollständige Feeds:Aktualisieren Sie die Entität aus den vollständigen Feeds, damit isDisabled vor dem nächsten Abruf durch Google auf true gesetzt ist. Andernfalls wird die Entität wieder aktiviert.
Bestimmter Artikel nicht auf Lager
MenuItemOffer
Echtzeitaktualisierungen:Senden Sie das kapselnde MenuItemOffer-Element mit inventoryLevel = 0 für die angegebene MenuItem und alle anderen Daten unverändert.
Preisänderung für Menüpunkt
MenuItemOffer
Echtzeitaktualisierungen:Senden Sie die umschließende MenuItemOffer-Entität mit price, das auf den aktualisierten Preis für die angegebene MenuItem festgelegt ist, und alle anderen Daten unverändert.
Neue Entität der obersten Ebene hinzufügen
Nur für Entitäten der Typen Menu, Restaurant und Service.
Menu, Restaurant, Service
Beispiel: Sie müssen einem Restaurant ein neues Menü hinzufügen.
Vollständige Feeds:Fügen Sie die Entität Ihren Datenfeeds hinzu und warten Sie auf die Batchaufnahme.
Entität der obersten Ebene endgültig löschen
Nur für Entitäten der Typen Menu, Restaurant und Service.
Vollständige Feeds:Entfernen Sie die Entität vor dem nächsten Abruf durch Google aus den vollständigen Feeds. Andernfalls wird sie wieder hinzugefügt.
Neues Liefergebiet in einer bestimmten Service hinzufügen
ServiceArea
Batchfeeds:Senden Sie die betreffende ServiceArea-Entität mit allen ihren Feldern wie gewohnt in den vollständigen Feeds, wobei das neue Auslieferungsgebiet in polygon, geoRadius oder postalCode angegeben ist.
Voraussichtliche Zustellung am Service aktualisieren
ServiceHours
Batchfeeds:Senden Sie die ServiceHours wie in den Feeds, mit der Ausnahme, dass die leadTimeMin entsprechend aktualisiert wird.
Lieferpreise in Service aktualisieren
Fee
Batchfeeds:Senden Sie die vollständige Auslieferung Fee mit aktualisiertem price.
Liefer- oder Abholzeiten in Service aktualisieren
ServiceHours
Batchfeeds:Senden Sie die ServiceHours wie in den Feeds, mit der Ausnahme, dass die opens- und closes-Attribute entsprechend aktualisiert werden.
Service (Mindestbestellwert ändern)
Fee
Batchfeeds:Senden Sie die vollständige Fee mit minPrice, das aktualisiert wurde.
MenuItem endgültig löschen
Menu
Batchfeeds:Geben Sie MenuItem wie in den Feeds an, aber lassen Sie parentMenuSectionId leer.
Verarbeitungszeiten für Batchjobs und Echtzeitupdates
Eine Entität, die über einen Batchfeed aktualisiert oder gelöscht wurde, wird innerhalb von zwei Stunden verarbeitet. Eine Entität, die über eine Echtzeitaktualisierung aktualisiert wurde, wird innerhalb von fünf Minuten verarbeitet. Ein veraltetes Element wird nach 14 Tagen gelöscht.
Sie können Google Folgendes senden:
Mehrere Batchjobs pro Tag, um Ihr Inventar auf dem neuesten Stand zu halten, ODER
Ein Batchjob pro Tag und Echtzeitaktualisierungen, damit Ihr Inventar immer auf dem neuesten Stand ist.
[null,null,["Zuletzt aktualisiert: 2024-11-26 (UTC)."],[[["This API enables partners to send time-sensitive inventory updates to Google, reflecting changes in the Google UI within five minutes."],["It supports `upsert` and `delete` operations for up to 1,000 entities per API call, processing requests asynchronously via a queue."],["Include changes made via real-time updates in your daily data feeds to maintain data consistency and avoid overwrites."],["For adding new entities, use batch ingestion instead of real-time updates, as it is not designed for this purpose."],["The `generation_timestamp` field ensures updates within a `batchPush` request are applied in the correct order, facilitating entity versioning."]]],[]]
