Google Search Console einrichten

Richten Sie Google Search Console ein, wenn Workspace externe Suchmetriken wie Suchanfragen, Seiten, Länder, Geräte, Impressionen, Klicks, CTR und durchschnittliche Position im Analytics-Tab einer Site anzeigen soll. Nach der Einrichtung importiert Workspace Search-Console-Daten als Taskstream-Job und schreibt sie in den provider-neutralen Search-Metric-Speicher.

Diese Seite richtet sich an Administratoren und Betreiber. Nach Abschluss ist die veröffentlichte Workspace-Site mit einer verifizierten Google-Search-Console-Property verbunden, ein erster Sync ist geprüft und ein täglicher Sync kann über das aktive Binding laufen. Workspace ersetzt keinen Google-Search-Console-Zugriff: Die Property muss bei Google vorhanden und für den verwendeten Google-Nutzer zugänglich sein.

Platzhalter

Die Beispiele verwenden diese Platzhalter:

Voraussetzungen

Prüfen Sie diese Punkte, bevor Sie Credential, Binding oder Sync anlegen:

Workspace stellt für diese Anbindung aktuell keinen öffentlichen OAuth-Consent-Wizard und keine Admin-UI zum Anlegen des Bindings bereit. Legen Sie Credential und Binding deshalb über den freigegebenen Betreiber- oder Migrationsprozess an. Speichern Sie Access Token, Refresh Token, Client Secret, OAuth-Codes, DNS-Verifizierungswerte und private Schlüssel niemals in Tickets, Chats, Logs, Dokumentation oder Taskstream-Payloads.

Die Google-API-Dokumentation beschreibt die Autorisierung über OAuth 2.0 und den lesenden Scope webmasters.readonly in der Search-Console-Autorisierung. Die importierten Kennzahlen stammen aus der Search Analytics Query API. Google beschreibt im Search-Central-Leitfaden zu Traffic-Einbrüchen die Auswertung über die letzten 16 Monate und empfiehlt API oder Export, wenn Sie Daten darüber hinaus dauerhaft in eigenen Systemen speichern wollen: Debug Google Search Traffic Drops.

Kurzablauf

1. Prüfen Sie Workspace-Site, Domain-Bindung, Readiness und externe HTTPS-Erreichbarkeit.
2. Legen Sie die Google-Search-Console-Property an oder öffnen Sie die bestehende Property.
3. Aktivieren Sie die Search Console API im passenden Google-Cloud-Projekt.
4. Richten Sie den OAuth Consent Screen und den OAuth-Client mit ausschließlich lesendem Scope ein.
5. Importieren Sie das Google-OAuth-Credential über einen nicht-loggenden Betreiberprozess in den verschlüsselten Workspace-Credential-Store.
6. Legen Sie ein aktives Binding zwischen Tenant, Site, Property und Credential an.
7. Starten Sie einen Test-Sync und prüfen Sie ImportRun, Taskstream-Job und Summary.
8. Importieren Sie verfügbare historische Daten in Fenstern von höchstens 30 Tagen.
9. Richten Sie einen täglichen Sync ohne feste dateFrom/dateTo ein.

Workspace prüfen

Prüfen Sie Workspace, bevor Sie Google-OAuth oder Bindings anfassen:

1. Melden Sie sich im richtigen Tenant-Kontext an.
2. Prüfen Sie die Rechte external_search_metrics:read und external_search_metrics:sync.
3. Prüfen Sie die Site-Liste und bestätigen Sie <siteId>.
4. Prüfen Sie die Domain-Liste und bestätigen Sie <productionHost>.
5. Prüfen Sie die Web-Readiness der Site.
6. Prüfen Sie die externe HTTPS-Erreichbarkeit:

https://<productionHost>/
https://<productionHost>/sitemap.xml
https://<productionHost>/robots.txt

Brechen Sie ab, wenn die finale Produktionsdomain noch nicht gebunden, nicht öffentlich erreichbar oder nicht readiness-grün ist.

Google vorbereiten

1. Öffnen Sie Google Search Console und legen Sie die Property an oder öffnen Sie die bestehende Property.
2. Wählen Sie den Property-Typ bewusst:

• Domain Property für Domain, Subdomains und Protokolle.
• URL-Prefix Property für exakt eine HTTPS-URL.

1. Notieren Sie <propertyUrl> exakt. Verwenden Sie bei Domain Properties die von Google verwendete sc-domain:-Referenz, wenn Ihr Betreiberprozess diese Form erwartet.
2. Verifizieren Sie die Ownership, bei Domain Properties bevorzugt per DNS-TXT.
3. Prüfen Sie, dass der OAuth-Google-Nutzer Zugriff auf die Property hat.
4. Öffnen Sie Google Cloud Console und wählen Sie <googleCloudProject>.
5. Aktivieren Sie die Search Console API.
6. Richten Sie den OAuth Consent Screen ein:

• App-Name
• Support-E-Mail
• Entwicklerkontakt
• keine unnötigen Scopes

1. Fügen Sie nur diesen Scope hinzu:

https://www.googleapis.com/auth/webmasters.readonly

1. Tragen Sie im Testmodus den ausführenden Google-Nutzer als Testnutzer ein.
2. Erstellen Sie den OAuth-Client.
3. Speichern Sie die OAuth-Client-JSON-Datei lokal unter <oauthClientJsonLocalPath>. Committen Sie diese Datei nicht und kopieren Sie ihren Inhalt nicht in Chat, Ticket oder Dokumentation.

Credential importieren

Importieren Sie das Credential ausschließlich über einen freigegebenen, nicht-loggenden Betreiberprozess:

1. Führen Sie den OAuth-Flow lokal aus.
2. Geben Sie OAuth-Code, Access Token, Refresh Token und Client Secret nicht aus und dokumentieren Sie diese Werte nicht.
3. Verarbeiten Sie Token und Client Secret nur lokal im Betreiberprozess.
4. Prüfen Sie vor dem Speichern den Property-Zugriff gegen die Google API.
5. Speichern Sie Token und Client Secret ausschließlich verschlüsselt im Workspace-Credential-Store.
6. Verwenden Sie als Provider-Name google_search_console.
7. Dokumentieren Sie <credentialId>, aber keine Secret-Werte.

Entfernen Sie <oauthClientJsonLocalPath> nach erfolgreicher Einrichtung oder verwahren Sie die Datei sicher außerhalb des Repositories.

Binding anlegen

Legen Sie ein aktives Binding zwischen Workspace und Google Search Console an:

Dokumentieren Sie <bindingId>. Stellen Sie sicher, dass nur ein aktives Binding pro Site und Property existiert, wenn der Sync ohne explizite bindingId laufen soll. Bei mehreren aktiven Bindings muss jeder Sync die gewünschte bindingId angeben.

Test-Sync starten

Starten Sie den ersten Import über den Site-Analytics-Endpunkt:

POST /api/v1/site/analytics/sites/<siteId>/external-search/google-search-console/sync
Authorization: Bearer <token-mit-external_search_metrics:sync>
Content-Type: application/json

Ohne Body nutzt Workspace das aktive Binding der Site und syncLookbackDays:

{}

Ein erfolgreicher Aufruf liefert 202 Accepted mit Job-ID:

{
  "jobId": "<jobId>",
  "status": "accepted",
  "alreadyRunning": false
}

Wenn für dieselbe Binding-/Property-Kombination bereits ein aktiver Job läuft, liefert Workspace denselben aktiven Job zurück und setzt alreadyRunning auf true.

Überwachen Sie den Taskstream-Job bis zum Abschluss. Prüfen Sie danach den ImportRun:

Leere Werte können gültig sein, wenn Google für Property und Zeitraum noch keine Daten liefert.

Historischen Backfill importieren

Google Search Console stellt historische Performance-Daten nur begrenzt bereit. Google dokumentiert für den Performance-Kontext aktuell 16 Monate; prüfen Sie vor großen Backfills die aktuelle Google-Dokumentation und beginnen Sie mit dem ältesten noch verfügbaren vollständigen Tag.

Workspace akzeptiert pro Sync-Fenster höchstens 30 inklusive Tage. Teilen Sie den Backfill deshalb in Fenster von maximal 30 Tagen auf und warten Sie nach jedem Start auf den Taskstream-Abschluss.

Starten Sie jedes Fenster mit expliziter bindingId, dateFrom und dateTo:

{
  "bindingId": "<bindingId>",
  "dateFrom": "YYYY-MM-DD",
  "dateTo": "YYYY-MM-DD"
}

Workspace akzeptiert Datumswerte im Format YYYY-MM-DD. dateTo darf nicht nach gestern in UTC liegen. Dokumentieren Sie für jedes Fenster Zeitraum, Job-ID, ImportRun-ID, rowsRead, rowsWritten und Status.

Prüfen Sie nach dem Backfill die Summary über das volle Fenster. Der Parameter to ist exklusiv:

GET /api/v1/site/analytics/sites/<siteId>/external-search/summary?provider=google_search_console&from=<start>&to=<exclusiveEnd>
Authorization: Bearer <token-mit-external_search_metrics:read>

Dokumentieren Sie danach:

• frühestes gespeichertes Datum,
• spätestes gespeichertes Datum,
• Summe Impressionen,
• Summe Klicks,
• CTR,
• Average Position,
• Anzahl gespeicherter Aggregate Rows.

Täglichen Sync planen

Richten Sie nach Test-Sync und Backfill einen täglichen Sync ein:

1. Planen Sie den Sync einmal täglich.
2. Nutzen Sie nachts oder frühmorgens UTC, zum Beispiel 03:30 UTC.
3. Verwenden Sie keine festen dateFrom- oder dateTo-Werte.
4. Lassen Sie den Sync über <bindingId> und syncLookbackDays laufen, typischerweise mit 7 Tagen.
5. Begrenzen Sie die Parallelität pro Tenant, Site und Property auf 1.
6. Setzen Sie MaxRetries auf 3.
7. Setzen Sie RetryDelay auf 10 Minuten.

Der Lookback synchronisiert mehrere zurückliegende Tage erneut. So übernimmt Workspace verspätete oder von Google nachkorrigierte Daten, ohne alte Buckets zu duplizieren.

Nutzen Sie bevorzugt einen unterstützten Produkt- oder Admin-API-Pfad, wenn Ihre Installation dafür einen freigegebenen Scheduler-Pfad anbietet. Wenn kein solcher Pfad verfügbar ist, dürfen nur Plattformadmins einen begrenzten Taskstream-Cron-Job direkt anlegen. Die Taskstream-Payload enthält nur Referenzen:

{
  "tenant_id": "<tenant>",
  "site_id": "<siteId>",
  "binding_id": "<bindingId>"
}

Die Payload enthält keine Tokens, Client Secrets, OAuth-Codes, DNS-Verifizierungswerte oder privaten Schlüssel.

Prüfen Sie den angelegten täglichen Job:

Dokumentieren Sie klar, warum eine direkte Taskstream-Anlage nötig war, wenn kein unterstützter Produkt- oder Admin-API-Pfad verfügbar war.

Ergebnis prüfen

Lesen Sie die importierten Search-Metriken über:

GET /api/v1/site/analytics/sites/<siteId>/external-search/summary?provider=google_search_console
Authorization: Bearer <token-mit-external_search_metrics:read>

Die Antwort enthält aggregierte Werte für Impressionen, Klicks, CTR, durchschnittliche Position sowie Aufschlüsselungen nach Suchanfragen, Ländern, Seiten und Geräten. Workspace speichert diese Werte im provider-neutralen Analytics-Speicher. Taskstream-Jobdaten enthalten nur Tenant-, Site-, Binding- und Datumsreferenzen, keine OAuth-Tokens.

Im Site Manager sehen berechtigte Nutzer die importierten Kennzahlen unter CMS > Sites im Tab Analyse, Abschnitt Externe Suche, sobald der Taskstream-Job abgeschlossen ist und Google für den Zeitraum Daten geliefert hat.

Speicherung und Historie

Workspace speichert externe Search-Metriken provider-neutral aggregiert.

Re-Syncs derselben Buckets werden per Upsert aktualisiert, nicht als neue Version dupliziert. ImportRuns bleiben als Sync-Protokoll erhalten. Der Summary-Endpunkt aggregiert über gespeicherte Daten und unterstützt from und to.

Erfolg erkennen

Die Einrichtung funktioniert, wenn diese Prüfungen erfüllt sind:

Abbrechen, wenn

Brechen Sie die Einrichtung ab, wenn einer dieser Punkte zutrifft:

Betreiberprotokoll pflegen

Dokumentieren Sie die Einrichtung in Ihrem Betriebsprotokoll oder in der zuständigen Work Order. Halten Sie nur Referenzen und Ergebnisse fest:

• Status und Scope der Einrichtung,
• <tenant> und <siteId>,
• <productionHost> und beobachtete Readiness,
• <propertyUrl>,
• <credentialId>,
• <bindingId>,
• syncLookbackDays,
• Job-IDs und ImportRun-IDs,
• Sync- und Backfill-Zeiträume,
• rowsRead, rowsWritten und Status je Fenster,
• frühestes und spätestes gespeichertes Datum,
• täglicher Job mit <dailyCronSpec>,
• offene Risiken.

Dokumentieren Sie keine Secret-Werte. Prüfen Sie vor Commit oder Übergabe:

• keine OAuth-Client-JSON-Dateien im Git-Status,
• keine Access Tokens, Refresh Tokens, Client Secrets, OAuth-Codes, DNS-Verifizierungswerte oder privaten Schlüssel in Artefakten,
• Secret-Muster-Scan ausgeführt,
• Format-, Lint- oder Doku-Checks für neue Betreiberhilfen ausgeführt,
• git diff --check ohne Befund.

Fehlersuche

Nutzen Sie diese Prüfschritte, wenn der Import nicht startet oder keine Werte erscheinen:

Sicherheitsgrenzen

Verwenden Sie für Workspace nur den lesenden Scope https://www.googleapis.com/auth/webmasters.readonly. Der schreibende Scope https://www.googleapis.com/auth/webmasters ist für den Import von Search-Analytics-Daten nicht erforderlich.

Workspace schreibt keine Google-Credentials in Taskstream-Jobdaten, API-Antworten oder ImportRun-Fehlermeldungen. Behandeln Sie Google-OAuth-Daten trotzdem als Secrets und geben Sie sie nicht an Support-Tickets, Dokumentationsbeispiele oder Chatnachrichten weiter.

Taskstream-Payloads enthalten nur Tenant-, Site-, Binding- und Datumsreferenzen. Betreiberprozesse dürfen Secret-Werte weder loggen noch in Fehlermeldungen, Screenshots oder Betriebsprotokolle übernehmen.

Nächste Schritte

• Lesen Sie Website-Analytics im fachlichen Kontext: Website-Analytics und Marketing-Attribution
• Prüfen Sie API-Konventionen: OpenAPI verwenden