Aktualizacje interfejsu API w czasie rzeczywistym

Asortyment w Twoim systemie zmienia się w ciągu dnia z powodu nowych rezerwacji, anulowań i zmian w harmonogramie wprowadzonych przez sprzedawców. Interfejs API aktualizacji w czasie rzeczywistym to mechanizm powiadamiający Google o tych zmianach dostępności zasobów reklamowych. Możesz też korzystać z aktualizacji interfejsu API w czasie rzeczywistym, aby powiadamiać Google o zmianach wprowadzonych w istniejących rezerwacjach.

Aktualizacje w czasie rzeczywistym nie są konieczne, jeśli wszyscy sprzedawcy korzystają z funkcji listy oczekujących.

Aktualizacje interfejsu API w czasie rzeczywistym i pliki danych

Aktualizacje interfejsu API w czasie rzeczywistym służą do powiadamiania Google o przyrostowych zmianach dostępności zasobów reklamowych i rezerwacji w czasie rzeczywistym. Oprócz aktualizacji interfejsu API w czasie rzeczywistym przesyłaj też codziennie pełne pliki danych o dostępności, aby mieć pewność, że Google ma najdokładniejsze i aktualne informacje o dostępności w Twoim systemie. Pełne pliki danych działają jak migawka bieżącego stanu dostępności zasobów reklamowych w systemie.

Aktualizacje interfejsu API mogą służyć do aktualizowania dowolnych informacji przekazywanych w plikach danych, takich jak informacje o sprzedawcach i usługach, ale zwykle służą tylko do aktualizowania informacji o dostępności.

Wymagane interfejsy API aktualizacji w czasie rzeczywistym

Interfejsy API aktualizacji w czasie rzeczywistym (RTU)
BookingNotification	Obowiązkowe	wysyłać RTU do powiadomień za każdym razem, gdy nastąpi zmiana rezerwacji (np. zmodyfikowanie lub anulowanie).
Dostępność – zastąpienie RTU	Wymagana warunkowo[1]	Wyślij RTU zbiorcze lub pojedyncze, aby wysyłać aktualizacje dostępności asortymentu. Rozpowszechnienie i uwzględnienie zmian może potrwać kilka minut.
RTU sprzedawcy	Opcjonalnie	Wyślij RTU dla sprzedawców, jeśli chcesz wprowadzać zmiany w informacjach o sprzedawcy w czasie rzeczywistym. Rozpowszechnienie i uwzględnienie zmian może potrwać kilka godzin.
RTU usługi	Opcjonalnie	Wyślij RTU dotyczące usługi, jeśli chcesz wprowadzać zmiany w informacjach o usłudze w czasie rzeczywistym. Typowym przypadkiem użycia jest gwałtowne wahania cen usług w ciągu dnia. Zalecamy wdrożenie RTU usług, aby uniknąć błędów zamówień z powodu niezgodności cen. Rozpowszechnienie i uwzględnienie zmian może potrwać kilka godzin.

Dostępność Zastąp API RTU

Użyj interfejsu Availability Replace API, aby aktualizować dostępność w tych przypadkach użycia:

• Użytkownik rezerwuje rezerwację w Twoim systemie, więc przedział dostępności nie jest już dostępny.
• Sprzedawca zmienia dostępność w Twoim systemie.
• Użytkownik rezerwuje rezerwację przez Google, więc przedział dostępności nie jest już dostępny.
• Rezerwacja dokonana w Google zostanie anulowana po Twojej stronie, na przykład bezpośrednio przez sprzedawcę. Musisz zaktualizować zarówno rezerwację, jak i dostępność, ponieważ pierwotny termin jest znów dostępny.
• Wywołanie BatchAvailabilityLookup serwera rezerwacji zwraca zasoby reklamowe, które nie pasują do rzeczywistych.

Więcej informacji znajdziesz w tych materiałach:

• Samouczek: jak uporządkować aktualizacje w czasie rzeczywistym
• Przykład klienta Java do aktualizacji w czasie rzeczywistym za pomocą wywołań REST
• Strona informacyjna interfejsu API aktualizacji zasobów reklamowych

Interfejs API rezerwacji powiadomień RTU

Interfejsy Booking Notification API powiadamia Google o aktualizacjach istniejących rezerwacji. Gdy wysyłasz informacje o anulowaniach, wysyłaj w żądaniu tylko najważniejsze informacje z parametrem zapytania updateMask. Oto przykład:

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

Dostęp do interfejsu API

Tworzenie konta usługi

Na karcie Dane logowania w Konsoli interfejsów API Google utwórz konto usługi. Przechowuj klucz prywatny w formacie JSON w bezpiecznym miejscu. Podczas tworzenia konta możesz ustawić rolę na „Właściciel”.

Uwierzytelnianie interfejsów API rezerwacji w Mapach Google

Po utworzeniu konta usługi uwierzytelnij te interfejsy API:

• Google Maps Booking API
• Google Maps Booking API (wersja deweloperska)

Szczegółowe instrukcje znajdziesz w samouczku Uwierzytelnianie za pomocą interfejsu Maps Booking API.

Używanie wywołań REST lub pobieranie biblioteki klienta

Zalecamy wykonywanie wywołań REST bezpośrednio do interfejsu Maps Booking API z ładunkami JSON. Więcej informacji znajdziesz w dokumentacji interfejsu API REST.

Do połączenia z interfejsem API możesz też użyć bibliotek klienta.

Język	Link do pobrania
Java	Biblioteka klienta Java. Więcej informacji znajdziesz w instrukcjach dotyczących klienta Java.

Dostępne do pobrania są dodatkowe biblioteki pomocnicze, które obsługują autoryzację i inne aspekty wywołań interfejsów API Google. W razie potrzeby spójrz na te przykłady.

Pobierz dokument Discovery

W przypadku niektórych bibliotek klienta, takich jak Ruby, trzeba pobrać dokument Discovery interfejsu API, który opisuje jego metody i parametry.

Aby pobrać dokument Discovery, użyj tego polecenia:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

Więcej informacji o uzyskiwaniu dostępu do interfejsu API z poziomu Ruby znajdziesz w tych artykułach: Klient interfejsu API Ruby i Biblioteka uwierzytelniania Ruby.

Autoryzowane wywołania interfejsu API

Gdy wywołujesz interfejs API, przeczytaj sekcję o przygotowywaniu autoryzowanego wywołania interfejsu API, aby autoryzować swoje konto usługi za pomocą klucza prywatnego i tego zakresu OAuth: https://www.googleapis.com/auth/mapsbooking.

Limity interfejsu API

Aktualizacje interfejsu API mają limit 1500 żądań co 60 sekund, czyli średnio 25 żądań na sekundę. W przypadku przekroczenia limitu (co może wystąpić, gdy nie dodasz prawidłowego numeru projektu Google Cloud w portalu dla partnerów), Google w odpowiedzi wyświetli ten komunikat o błędzie:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

Aby rozwiązać ten problem, ponawiaj próby wywołania w rosnących wykładniczo odstępach czasu, aż się uda. Jeśli regularnie wyczerpujesz limit na korzystaniu z ReplaceServiceAvailability, przejdź na BatchReplaceServiceAvailabily, aby zmniejszyć liczbę wywołań interfejsu API. Ta metoda umożliwia zaktualizowanie wielu usług w pojedynczym wywołaniu interfejsu API.

Piaskownica i punkty końcowe środowiska produkcyjnego

Możesz wywoływać za pomocą interfejsu API zarówno środowisko piaskownicy, jak i środowisko produkcyjne. Upewnij się, że w projekcie Google Cloud masz włączone oba interfejsy API. Oba interfejsy API korzystają z tego samego zakresu, ale mają różne punkty końcowe.

Punkt końcowy produkcyjny: https://mapsbooking.googleapis.com/

Punkt końcowy piaskownicy: https://partnerdev-mapsbooking.googleapis.com/

Oto przykład w języku Java, który pokazuje, jak przełączać punkty końcowe:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()