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:

Legen Sie das Google-OAuth-Credential über System > Integrationen > Provider-Verbindungen an. Die allgemeine Anleitung steht in Provider-Verbindungen einrichten. Legen Sie danach das Search-Console-Binding ü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. Legen Sie das Google-OAuth-Credential über System > Integrationen > Provider-Verbindungen an.
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.

Bestehendes OAuth nach Release prüfen

Nach dem Release auf Provider-Verbindungen müssen vorhandene Search-Console-OAuths normalerweise nicht neu autorisiert werden. Workspace liest weiter aus provider_auth_tokens; der neue Resolver prüft zusätzlich Provider, Tenant, Credential-ID, Capability und Scope.

Prüfen Sie ein bestehendes Setup in dieser Reihenfolge:

1. Öffnen Sie System > Integrationen > Provider-Verbindungen.
2. Suchen Sie die Verbindung mit Provider google_search_console.
3. Vergleichen Sie die Konto-ID mit der Search-Console-Property oder der im Betreiberprozess verwendeten Property-Referenz.
4. Notieren Sie die angezeigte <credentialId>.
5. Führen Sie Testen für die Verbindung aus.
6. Prüfen Sie das Search-Console-Binding der Site:

• Tenant ist <tenant>.
• Site ist <siteId>.
• Provider ist google_search_console.
• Property ist <propertyUrl>.
• Credential ist dieselbe <credentialId>.
• Das Binding ist aktiv.

1. Starten Sie einen Test-Sync für ein kleines Zeitfenster oder ohne Body über syncLookbackDays.

Sie müssen das OAuth nur neu verbinden, wenn einer dieser Befunde auftritt:

Wenn Sie neu verbinden und dieselbe Konto-ID verwenden, aktualisiert Workspace den bestehenden Token-Datensatz. Wenn eine neue Credential-ID entsteht, muss das Search-Console-Binding auf diese neue ID zeigen.

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. Veröffentlichen, verifizieren oder erlauben Sie die OAuth-App für den produktiven Betrieb. Verwenden Sie den Testing-Modus nur für kurzfristige Tests.
2. Erstellen Sie den OAuth-Client und tragen Sie die Redirect URI aus System > Integrationen > Provider-Verbindungen ein.
3. Speichern Sie die OAuth-Client-Daten nur in einem sicheren Betreiberkontext. Committen Sie Client Secret oder OAuth-Client-JSON nicht und kopieren Sie diese Werte nicht in Chat, Ticket oder Dokumentation.

Credential anlegen

Legen Sie das Credential im Admin-Wizard an:

1. Öffnen Sie System > Integrationen > Provider-Verbindungen.
2. Wählen Sie Provider verbinden.
3. Wählen Sie Google Search Console.
4. Verwenden Sie als Konto-ID <propertyUrl> oder die im Betreiberprozess erwartete Property-Referenz.
5. Erfassen Sie Client ID und Client Secret des OAuth-Clients.
6. Prüfen Sie die angezeigte Redirect URI gegen den OAuth-Client in Google Cloud.
7. Öffnen Sie die Zustimmung und schließen Sie den OAuth-Dialog ab.
8. Dokumentieren Sie <credentialId> aus der Verbindungsliste, aber keine Secret-Werte.

Das Credential ist erfolgreich angelegt, wenn die Verbindungsliste Provider google_search_console, die Konto-ID, die Credential-ID und einen aktiven Status zeigt. Ein erfolgreicher Verbindungstest bestätigt Credential, Verschlüsselung, Refresh-Material und Scope. Er ersetzt nicht das fachliche Binding der Site.

Wenn der Verbindungstest nicht verfügbar oder auth_failed meldet, konnte Workspace das gespeicherte Google-Credential nicht erneuern. Ein bereits ungültiger oder widerrufener Refresh Token lässt sich nicht serverseitig reparieren. Prüfen Sie OAuth-App, Client Secret, Search-Console-Zugriff und Google-App-Status und nutzen Sie danach Neu verbinden in der Provider-Verbindungsliste. Workspace verwendet dabei die gespeicherte Client-ID und das verschlüsselte Client-Secret; Sie geben beide Werte nicht erneut ein. Nach erfolgreicher Zustimmung aktualisiert Workspace die bestehende Verbindung. Das bestehende Search-Console-Binding bleibt dann gültig.

Manuelle Search-Console-Sync-Jobs retryen solche Credential-Fehler nicht weiter. Starten Sie den Sync erst erneut, nachdem der Verbindungstest wieder erfolgreich ist.

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.

Das Binding ist korrekt, wenn Workspace die Credential-Referenz tenant- und provider-scoped akzeptiert. Ein Binding darf nie auf ein Credential eines anderen Tenants oder eines anderen Providers zeigen. Wenn Sie nach einem erneuten OAuth-Onboarding eine neue Credential-ID erhalten, aktualisieren Sie das Binding, bevor Sie den nächsten Sync starten.

Mit nucli prüfen

nucli kann Search-Console-Setup und Provider-Verbindungen prüfen, aber das OAuth-Onboarding nicht selbst durchführen. Der OAuth-Dialog läuft über System > Integrationen > Provider-Verbindungen.

Nützliche Prüfaufrufe:

nucli --tenant <tenant> api GET /api/v1/provider-connections --redact --save provider-connections.json
nucli --tenant <tenant> api POST /api/v1/provider-connections/<credentialId>/test --summary
nucli --tenant <tenant> api POST /api/v1/site/analytics/sites/<siteId>/external-search/google-search-console/sync --input sync.json --summary
nucli --tenant <tenant> api GET /api/v1/site/analytics/sites/<siteId>/external-search/google-search-console/status --summary
nucli --tenant <tenant> api GET '/api/v1/site/analytics/sites/<siteId>/external-search/summary?provider=google_search_console' --summary

Beispiel für sync.json mit explizitem Binding:

{
  "bindingId": "<bindingId>"
}

Nutzen Sie --summary oder --redact, wenn Sie Ergebnisse dokumentieren. Speichern Sie keine OAuth-Client-Daten, Tokens oder Google-Secret-Dateien für nucli-Aufrufe. Wenn ein Aufruf eine Eingabedatei braucht, legen Sie diese in einem geschützten Arbeitsverzeichnis ab und entfernen Sie sie nach der Prüfung.

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. Die KPI-Summen verwenden eigene Tages-Totals aus Google Search Console. Die Aufschlüsselungen verwenden die detailbasierten Search-Console-Zeilen nach Query, Page, Country und Device. Wenn für einen alten Zeitraum noch keine Tages-Totals vorliegen, kann die API für die KPI- Summen auf Detailzeilen zurückfallen und totalsSource entsprechend ausweisen.

Prüfen Sie den Importzustand über:

GET /api/v1/site/analytics/sites/<siteId>/external-search/google-search-console/status
Authorization: Bearer <token-mit-external_search_metrics:read>

Der Status zeigt pro Binding den letzten Lauf, den letzten erfolgreichen Lauf, das letzte importierte Datum sowie getrennte letzte Datumswerte für Tages- Totals und Detailzeilen. Die Antwort enthält keine OAuth-Tokens, Client Secrets oder Credential-Daten. Taskstream-Jobdaten enthalten nur Tenant-, Site-, Binding- und Datumsreferenzen.

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.

Workspace speichert zusätzlich interne Tages-Total-Buckets. Diese Buckets liefern die KPI-Summen der Summary. Detail-Buckets liefern die Tabellen nach Suchanfragen, Ländern, Seiten und Geräten. Google kann detailbasierte Zeilen aus Datenschutz- oder Aggregationsgründen unterzählen; deshalb dürfen diese Detailzeilen nicht als vollständiger Tages-Total-Vertrag interpretiert werden.

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