Google Indexing API dla Magento 2 - instalacja i konfiguracja
1. Ważne informacje przed wdrożeniem
Moduł integruje Magento 2 z Google Indexing API i pozwala dodawać adresy URL do centralnej kolejki zgłoszeń. Kolejka jest przetwarzana przez cron Magento, a każde zgłoszenie jest walidowane, deduplikowane, objęte limitami i logowane.
Zgodnie z dokumentacją Google, Indexing API jest oficjalnie przeznaczone przede wszystkim dla stron z danymi strukturalnymi:
JobPosting,BroadcastEventosadzone wVideoObject.
Użycie API dla produktów, kategorii, stron CMS lub wpisów blogowych nie gwarantuje indeksacji ani pozycji w wynikach wyszukiwania. Moduł należy traktować jako narzędzie techniczne do zgłaszania URL-i, a nie zamiennik sitemap XML, poprawnych canonicali, robots, hreflang, linkowania wewnętrznego i ogólnej jakości SEO.
Oficjalne materiały Google:
- https://developers.google.com/search/apis/indexing-api/v3/quickstart
- https://developers.google.com/search/apis/indexing-api/v3/prereqs
- https://developers.google.com/search/apis/indexing-api/v3/using-api
- https://developers.google.com/search/apis/indexing-api/v3/quota-pricing
2. Wymagania
Przed instalacją upewnij się, że środowisko spełnia wymagania:
- Magento 2.4.x,
- PHP 8.1 lub nowszy,
- Composer,
- działający cron Magento,
- możliwość instalacji pakietu
google/apiclient, - dostęp administracyjny do Magento,
- projekt Google Cloud z włączonym Indexing API,
- właściwość w Google Search Console zweryfikowana dla domeny sklepu,
- konto usługi Google dodane jako właściciel w Google Search Console.
Moduł wymaga pakietu:
google/apiclient:^2.16
Pakiet jest zadeklarowany w composer.json modułu, więc Composer powinien zainstalować go automatycznie.
3. Instalacja modułu
3.1. Instalacja przez Composer z repozytorium VCS
Jeżeli moduł jest instalowany z prywatnego lub publicznego repozytorium Git, dodaj repozytorium do projektu Magento:
composer config repositories.kowal composer https://repo.kowal.store
Jeżeli repozytorium jest prywatne, skonfiguruj token GitHub:
composer config http-basic.repo.kowal.store <YOUR E-MAIL> <YOUR-TOKEN>
Zainstaluj pakiet:
composer require kowal/module-google-indexing-api
Włącz moduł:
bin/magento module:enable Kowal_GoogleIndexingApi
Wykonaj aktualizację schematu bazy:
bin/magento setup:upgrade
Wyczyść cache:
bin/magento cache:flush
W trybie produkcyjnym wykonaj dodatkowo:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush
3.2. Instalacja lokalna w app/code
Jeżeli moduł jest instalowany bez Composera jako kod lokalny, umieść go w katalogu:
app/code/Kowal/GoogleIndexingApi
Następnie doinstaluj zależność Google API Client w projekcie Magento:
composer require google/apiclient:^2.16
Włącz moduł i wykonaj standardowe komendy Magento:
bin/magento module:enable Kowal_GoogleIndexingApi
bin/magento setup:upgrade
bin/magento cache:flush
Dla produkcji:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush
3.3. Weryfikacja instalacji
Sprawdź, czy moduł jest aktywny:
bin/magento module:status Kowal_GoogleIndexingApi
Po poprawnej instalacji w panelu administracyjnym powinny być dostępne:
Stores > Configuration > Kowal > Google Indexing API,- menu administracyjne
Google Indexing API > Indexing Queue, Google Indexing API > Import URLs,Google Indexing API > API Logs,Google Indexing API > Setup Assistant.
W bazie danych powinny powstać tabele:
kowal_google_indexing_queue,kowal_google_indexing_api_log.
4. Przygotowanie Google Cloud i Search Console
4.1. Utworzenie projektu Google Cloud
- Przejdź do Google Cloud Console.
- Utwórz nowy projekt albo wybierz istniejący projekt używany dla sklepu.
- Włącz API:
Indexing API
Bez włączonego API moduł nie będzie mógł poprawnie wysyłać zgłoszeń.
4.2. Utworzenie konta usługi
- W Google Cloud przejdź do
IAM & Admin > Service Accounts. - Utwórz nowe konto usługi.
- Wygeneruj klucz w formacie JSON.
- Pobierz plik JSON i przechowuj go bezpiecznie.
Moduł wymaga, aby JSON zawierał co najmniej pola:
type,project_id,private_key,client_email.
Pole type musi mieć wartość:
service_account
4.3. Dodanie konta usługi jako właściciela w Search Console
- Otwórz Google Search Console.
- Wybierz właściwość odpowiadającą domenie sklepu.
- Upewnij się, że właściwość jest zweryfikowana.
- Dodaj adres
client_emailz pliku JSON jako właściciela właściwości.
Przykład adresu konta usługi:
my-service-account@project-name.iam.gserviceaccount.com
Jeżeli konto usługi nie będzie właścicielem właściwości Search Console, Google może zwracać błędy uprawnień, np. brak potwierdzenia własności URL-a.
5. Konfiguracja modułu w Magento
Konfiguracja znajduje się w:
Stores > Configuration > Kowal > Google Indexing API
Konfiguracja obsługuje zakresy Magento:
- Default Config,
- Website,
- Store View.
Dzięki temu można mieć osobne ustawienia dla różnych sklepów lub widoków sklepu, jeżeli projekt tego wymaga.
6. Sekcja General
Enable
Domyślnie:
No
Włącza lub wyłącza działanie modułu.
Gdy pole ma wartość No, cron nie przetwarza kolejki. Adresy mogą istnieć w bazie, ale procesor kolejki nie będzie ich wysyłał do Google.
Rekomendacja:
- podczas pierwszej konfiguracji ustaw
Noalbo zostawDry Run = Yes, - po poprawnych testach ustaw
Yes.
Dry Run
Domyślnie:
Yes
Tryb testowy. Gdy Dry Run jest włączony, moduł przetwarza rekordy kolejki, zapisuje statusy i logi, ale nie wysyła realnego zgłoszenia do Google.
To najbezpieczniejszy tryb do pierwszego uruchomienia, testów konfiguracji i sprawdzenia, czy URL-e trafiają do kolejki zgodnie z oczekiwaniami.
Rekomendacja:
- pierwsze testy wykonuj zawsze z
Dry Run = Yes, - wyłącz
Dry Rundopiero po sprawdzeniu credentials, allowed hosts, kolejki i logów.
7. Sekcja Google Access Credentials
Credentials Source
Domyślnie:
Encrypted configuration value
Określa, skąd moduł pobiera JSON konta usługi Google.
Dostępne opcje:
| Opcja | Wartość techniczna | Opis |
|---|---|---|
Encrypted configuration value |
config |
JSON jest wklejany w konfiguracji Magento i zapisywany jako szyfrowana wartość sensitive config. |
Uploaded JSON file |
file |
JSON jest wgrywany jako plik i zapisywany poza katalogiem pub, w var/google-indexing. |
Rekomendacja:
- dla prostych wdrożeń można użyć wartości szyfrowanej w konfiguracji,
- dla środowisk z kontrolą dostępu do plików wygodniejszy może być upload pliku JSON.
Service Account JSON
Widoczne, gdy Credentials Source = Encrypted configuration value.
W tym polu należy wkleić pełną zawartość pliku JSON konta usługi Google.
Moduł waliduje JSON przed zapisem. Sprawdzane są:
- poprawność formatu JSON,
- obecność pól
type,project_id,private_key,client_email, - wartość
type = service_account.
Wartość jest zapisywana jako szyfrowana konfiguracja Magento.
Service Account JSON File
Widoczne, gdy Credentials Source = Uploaded JSON file.
Pozwala wgrać plik JSON konta usługi Google.
Moduł:
- akceptuje tylko pliki z rozszerzeniem
.json, - waliduje zawartość pliku,
- sprawdza wymagane pola
type,project_id,private_key,client_email, - zapisuje plik poza katalogiem publicznym, w
var/google-indexing, - próbuje ustawić uprawnienia pliku na
0600, jeżeli pozwala na to sterownik plików.
Plik jest zapisywany z nazwą zależną od zakresu konfiguracji, np. dla zakresu globalnego:
var/google-indexing/service-account-default-0.json
Google Cloud Project ID
Pole tekstowe na identyfikator projektu Google Cloud.
W aktualnej implementacji modułu główna autoryzacja bazuje na danych z JSON konta usługi. Pole Google Cloud Project ID pełni funkcję informacyjną i porządkującą konfigurację, zwłaszcza gdy sklep korzysta z kilku środowisk lub kilku projektów Google Cloud.
Rekomendacja:
- wpisz wartość
project_idz pliku JSON, - używaj osobnych projektów Google Cloud dla środowisk produkcyjnych i testowych, jeżeli taka separacja jest przyjęta w projekcie.
8. Sekcja Queue and Limits
Daily Publish Limit
Domyślnie:
200
Określa maksymalną liczbę zgłoszeń publish, które moduł może wykonać w ciągu dnia.
Limiter liczy requesty typu:
publish,publish_dry_run.
Jeżeli limit zostanie wykorzystany, procesor kolejki nie pobierze kolejnych rekordów do wysłania aż do kolejnego okna dziennego.
Rekomendacja:
- zostaw
200, jeżeli projekt korzysta z domyślnego limitu onboardingowego Google, - zwiększ wartość tylko wtedy, gdy projekt Google Cloud ma zatwierdzony wyższy limit,
- ustawienie
0blokuje wysyłkę, ponieważ dostępna liczba slotów wyniesie0.
Requests Per Minute Limit
Domyślnie:
60
Określa maksymalną liczbę requestów publish na minutę.
Moduł porównuje tę wartość z liczbą requestów zapisanych w logach z ostatniej minuty. Jeżeli limit minutowy jest wykorzystany, cron nie przetworzy kolejnych rekordów w danym przebiegu.
Rekomendacja:
- dla typowego wdrożenia zostaw wartość domyślną,
- zmniejsz wartość, jeżeli chcesz bardziej konserwatywnie obciążać API,
- nie ustawiaj
0, chyba że chcesz tymczasowo zatrzymać wysyłkę.
Cron Batch Size
Domyślnie:
20
Określa maksymalną liczbę rekordów kolejki przetwarzanych w jednym przebiegu crona.
Rzeczywista liczba przetworzonych rekordów jest ograniczana również przez:
Daily Publish Limit,Requests Per Minute Limit,- liczbę rekordów gotowych do wysłania,
- status i datę
scheduled_at.
Rekomendacja:
20jest bezpieczną wartością startową,- przy dużych kolejkach można zwiększyć wartość, ale tylko z uwzględnieniem limitów Google.
Default Indexing Lag (minutes)
Domyślnie:
15
Określa domyślne opóźnienie między dodaniem URL-a do kolejki a momentem, od którego może zostać wysłany.
Opóźnienie pomaga:
- ograniczyć duplikaty,
- uniknąć wysyłki po każdej drobnej zmianie,
- dać administratorowi czas na korektę treści,
- lepiej zarządzać limitem API.
W aktualnej implementacji to ustawienie jest używane wtedy, gdy zgłoszenie nie ma własnego opóźnienia.
Manual Form Indexing Lag (minutes)
Domyślnie:
15
Określa opóźnienie dla URL-i dodanych przez formularz:
Google Indexing API > Import URLs
Jeżeli administrator wklei listę URL-i ręcznie, każdy poprawny adres zostanie zaplanowany z tym opóźnieniem.
Rekomendacja:
- ustaw
0, jeżeli ręczny import ma trafiać do kolejki natychmiast, - zostaw
15, jeżeli chcesz zachować bufor na deduplikację i kontrolę zgłoszeń.
Mass Action Indexing Lag (minutes)
Domyślnie:
15
Określa opóźnienie dla URL-i dodanych przez:
- akcje masowe produktów,
- akcje masowe stron CMS,
- przyciski zgłaszania indeksacji na ekranach edycji produktu, kategorii i strony CMS.
Rekomendacja:
- dla masowych operacji zostaw wartość
15lub większą, - dla małych sklepów i ręcznej pracy administracyjnej można rozważyć niższą wartość.
Max Attempts
Domyślnie:
5
Określa maksymalną liczbę prób wysłania jednego rekordu kolejki.
Jeżeli Google zwróci błąd tymczasowy, moduł ustawi status retry, o ile liczba prób jest mniejsza niż Max Attempts. Po przekroczeniu limitu rekord otrzyma status failed_permanent.
Błędy traktowane jako tymczasowe:
408,409,412,429,500,502,503,504.
Retry Delay (minutes)
Domyślnie:
15
Podstawowe opóźnienie przed kolejną próbą wysyłki po błędzie tymczasowym.
Cron używa narastającego opóźnienia. Mnożnik zależy od liczby prób i jest ograniczony maksymalnie do 24. Dzięki temu kolejne próby nie są wykonywane zbyt agresywnie.
Przykład dla wartości 15:
| Próba | Przybliżone opóźnienie |
|---|---|
| 1 | 15 minut |
| 2 | 30 minut |
| 3 | 60 minut |
| 4 | 120 minut |
Allowed Source Types
Domyślnie:
manual,product,category,cms_page,amasty_blog_post
Lista dozwolonych typów źródeł, oddzielona przecinkami.
Obsługiwane wartości:
| Wartość | Znaczenie |
|---|---|
manual |
URL dodany ręcznie przez formularz importu. |
product |
URL produktu. |
category |
URL kategorii. |
cms_page |
URL strony CMS. |
amasty_blog_post |
URL wpisu Amasty Blog, jeżeli używany jest osobny moduł integracyjny. |
Jeżeli typ źródła nie znajduje się na liście, scheduler pominie zgłoszenie i oznaczy je jako skipped.
Rekomendacja:
- zostaw wartości domyślne, jeżeli sklep korzysta ze wszystkich standardowych źródeł,
- usuń źródła, których nie chcesz dopuszczać do kolejki.
Allowed URL Hosts
Domyślnie:
puste
Lista dozwolonych hostów URL, oddzielona przecinkami.
Przykład:
example.com,www.example.com
Jeżeli lista jest uzupełniona, moduł przyjmie tylko adresy należące do wskazanych hostów. Jeżeli URL ma inny host, walidacja zwróci błąd:
host_not_allowed
Rekomendacja:
- na produkcji zawsze uzupełnij tę listę,
- dodaj wszystkie hosty używane przez sklep, np. domenę główną, wersję
www, domeny store view i domeny językowe, - nie dodawaj domen testowych do konfiguracji produkcyjnej.
Require HTTPS URLs
Domyślnie:
Yes
Wymusza, aby zgłaszane adresy URL używały schematu https.
Jeżeli pole jest włączone, adres z http zostanie odrzucony z błędem:
https_required
Rekomendacja:
- dla produkcyjnych sklepów zostaw
Yes, Nostosuj tylko w wyjątkowych środowiskach testowych.
9. Sekcja Auto-Indexing
Enable Auto-Indexing
Domyślnie:
No
Pole jest przygotowane pod automatyczne integracje zapisu lub usuwania encji oraz dodatkowych providerów URL-i.
W aktualnym zakresie modułu dostępne są ręczne i administracyjne mechanizmy dodawania URL-i do kolejki, m.in. import URL-i, Mass Actions oraz przyciski na formularzach edycji.
Rekomendacja:
- zostaw
No, jeżeli auto-indexing nie został wdrożony w projekcie, - włącz dopiero wtedy, gdy projekt zawiera obsługę automatycznych zdarzeń encji korzystającą z tej konfiguracji.
10. Sekcja Logs
API Log Retention Days
Domyślnie:
90
Określa liczbę dni przechowywania logów API.
Cron czyszczący logi działa codziennie o:
03:15
Usuwa wpisy starsze niż liczba dni ustawiona w tym polu.
Rekomendacja:
90dni jest rozsądną wartością diagnostyczną,- przy dużej liczbie requestów można zmniejszyć retencję,
- przy audytach SEO można zwiększyć retencję, pamiętając o rozmiarze tabeli logów.
11. Asystent instalacji i konfiguracji
Asystent znajduje się w:
Google Indexing API > Setup Assistant
Jego celem jest szybkie sprawdzenie, czy konfiguracja po stronie Magento i Google jest gotowa do pierwszego testu.
11.1. Sekcja Current Status
Asystent pokazuje bieżący stan najważniejszych elementów:
| Pole | Znaczenie |
|---|---|
Module |
Informuje, czy moduł jest włączony w konfiguracji. |
Dry Run |
Informuje, czy aktywny jest tryb testowy bez realnej wysyłki do Google. |
Credentials |
Pokazuje, czy moduł potrafi odczytać i sparsować credentials Google. |
Service Account Email |
Wyświetla client_email z JSON konta usługi. Ten adres należy dodać jako właściciela w Search Console. |
Allowed Hosts |
Pokazuje listę hostów dopuszczonych w konfiguracji. |
Queue |
Pokazuje liczbę rekordów w statusach scheduled, pending, retry i failed_permanent. |
Jeżeli Credentials ma status Missing or invalid, należy wrócić do konfiguracji i poprawić JSON lub plik credentials.
Jeżeli Allowed Hosts pokazuje Not configured, moduł nie ogranicza hostów. Technicznie może to działać, ale produkcyjnie zalecane jest jawne wpisanie hostów sklepu.
11.2. Sekcja Setup Steps
Asystent wyświetla listę kroków potrzebnych przed pierwszym realnym requestem:
- Utworzenie lub wybór projektu Google Cloud.
- Włączenie Indexing API i utworzenie JSON key dla konta usługi.
- Wklejenie JSON albo wgranie pliku JSON w konfiguracji Magento.
- Dodanie service account email jako właściciela w Google Search Console.
- Uruchomienie testów, a następnie import jednego URL-a przy włączonym
Dry Run.
Asystent zawiera linki do:
- Google Cloud dla Indexing API,
- konfiguracji modułu w Magento,
- Google Search Console.
11.3. Test Google Credentials
Przycisk:
Test Google Credentials
sprawdza, czy Magento potrafi użyć danych konta usługi do uzyskania tokenu OAuth dla zakresu:
https://www.googleapis.com/auth/indexing
Pozytywny wynik oznacza, że:
- JSON jest poprawny,
- klucz prywatny może zostać użyty,
- Google wydał token OAuth.
Negatywny wynik może oznaczać:
- niepoprawny JSON,
- błędny lub uszkodzony
private_key, - brak wymaganego pola w JSON,
- problem z komunikacją z Google,
- użycie klucza, który nie jest kluczem konta usługi.
Ten test nie potwierdza jeszcze, że konto usługi ma dostęp właścicielski do domeny w Search Console. Do tego potrzebny jest test URL metadata albo realne zgłoszenie testowego URL-a.
11.4. Test URL Metadata
Formularz:
Test URL Metadata
pozwala wpisać publiczny URL z dozwolonego hosta i wykonać request metadata do Google Indexing API.
Przed wysłaniem requestu moduł:
- normalizuje URL,
- sprawdza, czy URL jest absolutny,
- sprawdza schemat
httplubhttps, - przy włączonym
Require HTTPS URLswymagahttps, - sprawdza
Allowed URL Hosts, jeżeli zostały skonfigurowane.
Możliwe wyniki:
| Wynik | Znaczenie |
|---|---|
| Sukces HTTP 2xx | Google zwrócił metadata dla URL-a. |
| HTTP 404 | Często oznacza, że URL nie ma jeszcze wcześniejszego skutecznego zgłoszenia przez Indexing API. To nie musi oznaczać błędnej konfiguracji. |
| Błąd walidacji przed requestem | URL nie spełnia warunków modułu, np. zły host, brak HTTPS albo nieabsolutny adres. |
| Błąd HTTP inny niż 404 | Należy sprawdzić komunikat Google, uprawnienia Search Console, credentials i limity. |
Metadata test nie tworzy nowego zgłoszenia publish. Służy do diagnostyki połączenia i statusu URL-a.
12. Pierwsze uruchomienie krok po kroku
Rekomendowana kolejność pierwszego uruchomienia:
- Zainstaluj moduł i uruchom
setup:upgrade. - W Magento przejdź do
Stores > Configuration > Kowal > Google Indexing API. - Ustaw
Enable = Yes. - Zostaw
Dry Run = Yes. - Wybierz źródło credentials.
- Wklej JSON konta usługi albo wgraj plik JSON.
- Uzupełnij
Google Cloud Project IDwartościąproject_idz JSON. - Uzupełnij
Allowed URL Hosts, np.example.com,www.example.com. - Zostaw domyślne limity, jeżeli Google nie zatwierdził wyższych limitów.
- Zapisz konfigurację i wyczyść cache.
- Przejdź do
Google Indexing API > Setup Assistant. - Sprawdź, czy asystent pokazuje credentials jako gotowe.
- Kliknij
Test Google Credentials. - Dodaj service account email jako właściciela w Google Search Console, jeżeli nie zostało to jeszcze wykonane.
- Wykonaj
Test URL Metadatadla publicznego URL-a z dozwolonego hosta. - Przejdź do
Google Indexing API > Import URLs. - Dodaj jeden testowy URL z akcją
URL_UPDATED. - Uruchom cron Magento:
bin/magento cron:run
- Sprawdź
Google Indexing API > Indexing Queue. - Sprawdź
Google Indexing API > API Logs. - Jeżeli wszystko działa poprawnie, wyłącz
Dry Run. - Dodaj ponownie jeden testowy URL i sprawdź realną odpowiedź Google.
13. Import URL-i z panelu administracyjnego
Import ręczny znajduje się w:
Google Indexing API > Import URLs
Formularz zawiera pola:
| Pole | Opis |
|---|---|
Action |
Typ zgłoszenia do Google: dodanie/aktualizacja albo usunięcie. |
Store View |
Store view, do którego ma być przypisane zgłoszenie. Dostępna jest też opcja globalna Use global/no store. |
URLs |
Lista absolutnych URL-i, po jednym adresie w linii. |
Dostępne akcje:
| Akcja w formularzu | Wartość API | Znaczenie |
|---|---|---|
Submit URLs for indexing |
URL_UPDATED |
Informuje Google, że URL został dodany albo zaktualizowany. |
Delete URLs from indexing |
URL_DELETED |
Informuje Google, że URL został usunięty i może zostać usunięty z indeksu. |
Po wysłaniu formularza moduł pokaże podsumowanie:
- dodane,
- zaktualizowane,
- zdeduplikowane,
- niepoprawne,
- pominięte.
Pierwsze 10 komunikatów walidacyjnych jest pokazywane jako notice w panelu administracyjnym.
14. Kolejka indeksowania
Kolejka znajduje się w:
Google Indexing API > Indexing Queue
Każdy rekord kolejki zawiera m.in.:
- URL,
- hash URL-a,
- store ID,
- website ID,
- typ źródła,
- ID encji źródłowej,
- pochodzenie requestu,
- akcję
URL_UPDATEDlubURL_DELETED, - status,
- priorytet,
- liczbę prób,
- maksymalną liczbę prób,
- datę planowanej wysyłki,
- datę przetworzenia,
- ostatni kod błędu,
- ostatni powód błędu,
- ostatni komunikat błędu,
- odpowiedź Google,
- informację
created_by.
Statusy kolejki
| Status | Znaczenie |
|---|---|
scheduled |
URL jest zaplanowany, ale czeka jeszcze na datę scheduled_at. |
pending |
URL jest gotowy do przetworzenia przez cron. |
processing |
URL jest aktualnie przetwarzany. |
success |
Google zwrócił odpowiedź sukcesu. |
retry |
Wystąpił błąd tymczasowy i rekord czeka na kolejną próbę. |
failed_permanent |
Wysyłka zakończyła się trwale albo przekroczono maksymalną liczbę prób. |
cancelled |
Rekord został ręcznie anulowany. |
Akcje na rekordach kolejki
| Akcja | Działanie |
|---|---|
Transmit Now |
Ustawia rekord jako pilny, blokuje go, wysyła natychmiast przez klienta Google i zapisuje wynik. |
Retry |
Ustawia rekord jako pending, czyści blokadę i planuje ponowną próbę od razu. |
Cancel |
Ustawia status cancelled i czyści blokadę. |
Uwaga: Transmit Now wykonuje realny request, jeżeli Dry Run = No. Przy Dry Run = Yes zostanie zapisany log dry-run bez realnej wysyłki do Google.
15. Cron
Moduł dodaje dwa zadania cron w grupie default.
Przetwarzanie kolejki
kowal_google_indexing_process_queue
Harmonogram:
*/5 * * * *
Zadanie uruchamia procesor kolejki co 5 minut.
Procesor:
- Sprawdza, czy moduł jest włączony.
- Zwalnia stare blokady rekordów
processingstarsze niż 30 minut. - Przenosi rekordy
scheduleddopending, jeżelischeduled_at <= now. - Sprawdza dostępne sloty w limitach dziennym i minutowym.
- Pobiera rekordy
pendingiretry. - Sortuje je według priorytetu i daty planowanej wysyłki.
- Wysyła request do Google albo wykonuje dry-run.
- Zapisuje odpowiedź, status i log API.
Czyszczenie logów
kowal_google_indexing_cleanup_logs
Harmonogram:
15 3 * * *
Zadanie usuwa logi API starsze niż liczba dni ustawiona w polu:
API Log Retention Days
16. Logi API
Logi są dostępne w:
Google Indexing API > API Logs
Log obejmuje:
- ID rekordu kolejki,
- store ID,
- typ requestu,
- URL endpointu,
- payload,
- status HTTP,
- body odpowiedzi,
- czas trwania requestu,
- datę utworzenia logu.
Typy requestów:
| Typ | Znaczenie |
|---|---|
publish |
Realne zgłoszenie URL-a do Google. |
publish_dry_run |
Przetworzenie w trybie dry-run bez realnego requestu do Google. |
metadata |
Test metadata dla URL-a. |
17. Mass Actions i przyciski administracyjne
Moduł dodaje mechanizmy zgłaszania URL-i z panelu administracyjnego.
Produkty
Na gridzie produktów dostępna jest akcja masowa dodająca URL-e produktów do kolejki.
Moduł pomija produkty:
- wyłączone,
- niewidoczne indywidualnie.
URL-e są generowane na podstawie URL rewrites dla aktywnych store view.
Strony CMS
Na gridzie stron CMS dostępna jest akcja masowa dodająca URL-e stron do kolejki.
Moduł pomija strony nieaktywne.
Jeżeli strona CMS jest przypisana do wszystkich store view, moduł rozwiązuje URL-e dla wszystkich store view.
Produkt, kategoria i strona CMS - przyciski na formularzu edycji
Moduł dodaje przyciski zgłaszania indeksacji na ekranach edycji:
- produktu,
- kategorii,
- strony CMS.
Przycisk rozwiązuje URL-e encji dla store view i dodaje je do kolejki jako URL_UPDATED.
18. Rekomendowana konfiguracja startowa
Dla pierwszego wdrożenia produkcyjnego:
| Pole | Rekomendacja |
|---|---|
Enable |
Yes po zapisaniu credentials i allowed hosts. |
Dry Run |
Yes na czas testów, później No. |
Credentials Source |
Encrypted configuration value albo Uploaded JSON file, zgodnie z polityką projektu. |
Google Cloud Project ID |
project_id z JSON. |
Daily Publish Limit |
200, chyba że Google zatwierdził wyższy limit. |
Requests Per Minute Limit |
60 albo mniej przy ostrożnym wdrożeniu. |
Cron Batch Size |
20. |
Default Indexing Lag |
15. |
Manual Form Indexing Lag |
0-15, zależnie od sposobu pracy administratorów. |
Mass Action Indexing Lag |
15. |
Max Attempts |
5. |
Retry Delay |
15. |
Allowed Source Types |
manual,product,category,cms_page,amasty_blog_post. |
Allowed URL Hosts |
Wszystkie produkcyjne hosty sklepu. |
Require HTTPS URLs |
Yes. |
Enable Auto-Indexing |
No, chyba że projekt wdraża automatyczne providery. |
API Log Retention Days |
90. |
19. Typowe problemy i diagnostyka
Credentials test failed
Sprawdź:
- czy JSON jest poprawny,
- czy JSON pochodzi z konta usługi,
- czy zawiera
private_keyiclient_email, - czy pole
typema wartośćservice_account, - czy plik JSON nie został uszkodzony podczas wklejania.
Google zwraca błąd uprawnień
Sprawdź:
- czy domena jest zweryfikowana w Search Console,
- czy
client_emailkonta usługi jest dodany jako właściciel, - czy testowany URL należy do tej samej właściwości Search Console,
- czy używasz właściwego projektu Google Cloud i właściwego JSON.
URL jest odrzucany przed wysyłką
Sprawdź komunikat walidacji:
| Komunikat | Przyczyna |
|---|---|
empty_url |
Pusty URL. |
url_too_long |
URL ma więcej niż 2048 znaków. |
url_not_absolute |
URL nie ma schematu lub hosta. |
https_required |
Włączono wymóg HTTPS, a URL używa HTTP. |
invalid_scheme |
Schemat nie jest http ani https. |
host_not_allowed |
Host URL-a nie znajduje się w Allowed URL Hosts. |
Kolejka się nie przetwarza
Sprawdź:
- czy
Enable = Yes, - czy działa cron Magento,
- czy rekordy mają status
pendingalboretry, - czy
scheduled_atnie jest w przyszłości, - czy limity dzienne lub minutowe nie są wykorzystane,
- czy
Daily Publish LimitiRequests Per Minute Limitnie są ustawione na0.
Rekordy trafiają do retry
Sprawdź:
- status HTTP w rekordzie kolejki,
- log API,
- odpowiedź Google,
- czy nie występuje limit
429, - czy nie ma chwilowych błędów
5xx, - czy
Max AttemptsiRetry Delaysą ustawione zgodnie z oczekiwaniami.
20. Opcjonalna integracja z Amasty Blog
Integracja z Amasty Blog jest przewidziana jako osobny moduł:
Kowal_GoogleIndexingApiAmastyBlog
Pakiet:
kowal/module-google-indexing-api-amasty-blog
Ten moduł nie jest wymagany do działania głównej integracji. Należy instalować go tylko w projektach, które używają amasty/blog i potrzebują akcji masowej dla wpisów blogowych.






















