Google Sheets einrichten — Service-Account & JSON-Schlüssel

SheetForge liest Google Sheets in zwei Modi.

ExportUrl benötigt keine Zugangsdaten: Teilen Sie die Tabelle per Link, registrieren Sie den #gid=-Wert jedes Tabs, und importieren Sie. Dieser Modus ist schreibgeschützt.
SheetsApi authentifiziert sich als Google-Service-Account und schaltet alles Weitere frei: private Tabellen, Rückschreiben (Übernehmen) und Push.

Diese Seite führt Sie Schritt für Schritt durch die komplette SheetsApi-Einrichtung — das Anlegen des Service-Accounts, das Herunterladen seines JSON-Schlüssels, das Teilen Ihrer Tabelle damit und das Verweisen von SheetForge auf den Schlüssel. Vorkenntnisse in Google Cloud werden nicht vorausgesetzt; jeder Schritt findet im Webbrowser statt und kostet nichts.

Der gesamte Ablauf:

Erstellen Sie ein Google-Cloud-Projekt.
Aktivieren Sie darin die Google Sheets API.
Erstellen Sie einen Service-Account.
Laden Sie den JSON-Schlüssel des Accounts herunter.
Teilen Sie Ihre Tabelle mit der E-Mail-Adresse des Accounts.
Verweisen Sie SheetForge auf den Schlüssel.

1. Ein Google-Cloud-Projekt erstellen

Öffnen Sie console.cloud.google.com und melden Sie sich mit einem Google-Konto an — es muss nicht dasjenige sein, dem die Tabelle gehört. Ein privates Konto funktioniert immer; manche Unternehmensorganisationen mit Google Workspace deaktivieren per Richtlinie das Herunterladen von Service-Account-Schlüsseln, wodurch Schritt 4 mit einem Organisationsrichtlinien-Fehler fehlschlägt (siehe „Wenn etwas fehlschlägt" unten). Bestätigen Sie beim ersten Besuch den Nutzungsbedingungen-Hinweis, um zur Konsole zu gelangen.
Klicken Sie oben in der Leiste auf den Projektwähler (das Dropdown neben dem Google-Cloud-Logo), dann auf New project.
Geben Sie einen beliebigen Namen ein (zum Beispiel sheetforge-sheets) und klicken Sie auf Create. Lassen Sie Organisation und Standort auf ihren Standardwerten.
Wenn die Benachrichtigung „project created" erscheint, wählen Sie das neue Projekt im Projektwähler aus. Alles Weitere geschieht innerhalb dieses Projekts — stellen Sie sicher, dass es ausgewählt bleibt.

Ein Projekt ist einfach ein Container für API-Einstellungen. Das Erstellen ist kostenlos, und die in dieser Anleitung beschriebene Nutzung der Sheets API verursacht keine Kosten.

2. Die Google Sheets API aktivieren

Öffnen Sie das Menü links (☰) und gehen Sie zu APIs & Services ▸ Library.
Suchen Sie nach Google Sheets API und öffnen Sie das Ergebnis.
Klicken Sie auf Enable. Steht auf der Schaltfläche Manage, ist die API bereits aktiviert — nichts zu tun.

3. Einen Service-Account erstellen

Ein Service-Account ist eine maschinelle Identität mit einer eigenen E-Mail-Adresse. SheetForge meldet sich als diese Identität an — Ihr persönliches Google-Passwort ist dabei nie im Spiel.

Gehen Sie zu APIs & Services ▸ Credentials.
Klicken Sie auf + Create credentials ▸ Service account.
Geben Sie einen Namen ein (zum Beispiel sheetforge-reader); die Account-ID wird automatisch ausgefüllt. Klicken Sie auf Create and continue.
Die Schritte „Grant this service account access to project" und „Grant users access" sind optional — überspringen Sie beide und klicken Sie auf Done. Der Zugriff auf Ihre Tabelle wird durch das Teilen der Tabelle (Schritt 5) gewährt, nicht durch Projektrollen.
Schlägt die Konsole vor, einen OAuth-Consent-Screen zu konfigurieren, ignorieren Sie das — Service-Accounts verwenden keinen.

4. Den JSON-Schlüssel herunterladen

Klicken Sie auf der Credentials-Seite auf den soeben erstellten Service-Account (unter „Service accounts").
Öffnen Sie den Tab Keys.
Klicken Sie auf Add key ▸ Create new key, wählen Sie JSON, und klicken Sie auf Create.
Der Browser lädt eine Datei mit einem Namen wie sheetforge-sheets-1a2b3c.json herunter. Dies ist die einzige Kopie — Google bewahrt sie nicht zum erneuten Herunterladen auf. Verlieren Sie sie, löschen Sie den Schlüssel im Tab Keys und erstellen Sie einen neuen.

Behandeln Sie diese Datei wie ein Passwort:

Verschieben Sie sie an einen Ort außerhalb Ihres Unity-Projekts und Repositorys, zum Beispiel C:/keys/sheetforge.json.
Legen Sie sie niemals unter Assets/ ab — alles dort wird mit dem Projekt committet, und eine versehentliche Referenz (oder ein Resources-/StreamingAssets-Ordner) kann sie in einen Build hineintragen.
Sollte der Schlüssel jemals durchsickern, löschen Sie ihn im Tab Keys (dies widerruft ihn sofort) und erstellen Sie einen neuen.

5. Die Tabelle mit dem Service-Account teilen

Der Schlüssel allein gewährt nichts. Der Service-Account kann nur Tabellen lesen, die explizit mit ihm geteilt wurden — genau wie bei einem menschlichen Mitarbeiter.

Öffnen Sie die heruntergeladene JSON-Datei in einem beliebigen Texteditor und kopieren Sie den Wert von client_email. Er sieht etwa so aus: sheetforge-reader@sheetforge-sheets.iam.gserviceaccount.com.
Öffnen Sie Ihre Tabelle in Google Sheets und klicken Sie auf Share.
Fügen Sie die Adresse ein und wählen Sie eine Rolle:
- Viewer genügt für den Import.
- Editor ist für das Rückschreiben erforderlich — Authoring-Übernehmen und Push.
Schalten Sie „Notify people" aus (die Adresse hat kein Postfach) und bestätigen Sie.
Warnt Google vor dem Teilen außerhalb Ihrer Organisation, bestätigen Sie trotzdem — ein Service-Account gehört zu keiner Organisation.

Diesen Schritt zu überspringen ist der häufigste Einrichtungsfehler — danach schlägt jede Anfrage mit einem Berechtigungsfehler fehl, egal wie korrekt der Schlüssel ist.

6. SheetForge auf den Schlüssel verweisen

Setzen Sie in Ihrem Import-Einstellungs-Asset die Source auf GoogleSheet und den Zugriffsmodus auf SheetsApi.
Füllen Sie spreadsheetId mit der langen ID aus der URL der Tabelle: https://docs.google.com/spreadsheets/d/<this part>/edit.
Teilen Sie SheetForge auf eine von zwei Arten mit, wo sich die Schlüsseldatei befindet:
- Empfohlen — Umgebungsvariable. Setzen Sie SHEETFORGE_SHEETS_KEY auf den absoluten Pfad der JSON-Datei. Jeder Entwickler setzt seine eigene; kein Pfad gelangt jemals ins Repository, und sie hat Vorrang vor dem Settings-Feld.
  - Unter Windows: setx SHEETFORGE_SHEETS_KEY "C:\keys\sheetforge.json" in einem Terminal, danach Unity und Unity Hub neu starten (bereits laufende Prozesse behalten ihre alte Umgebung).
  - Unter macOS/Linux: exportieren Sie sie in Ihrem Shell-Profil und starten Sie Unity aus dieser Shell heraus, oder verwenden Sie unter macOS launchctl setenv.
- Oder — Settings-Feld. Tragen Sie den Pfad in serviceAccountKeyPath ein, verweisend auf einen Ort außerhalb des Repositorys.
Klicken Sie auf ↓ Pull from source unter Tools ▸ SheetForge ▸ Data Studio. Ein erfolgreicher Bericht bedeutet, dass die gesamte Kette — Projekt, API, Account, Freigabe, Schlüssel — funktioniert.

Wenn etwas fehlschlägt

Berechtigungsfehler (PERMISSION_DENIED / 403): Die Tabelle ist nicht mit der client_email-Adresse geteilt (Schritt 5) — die ID zeigt auf eine reale Tabelle, die der Service-Account nicht sehen kann.
Requested entity was not found (404): spreadsheetId ist falsch — kopieren Sie exakt das Segment zwischen /d/ und /edit in der URL der Tabelle.
„Service account key creation is disabled" / Organisationsrichtlinien-Fehler in Schritt 4: Ihre Google-Workspace-Organisation erzwingt iam.disableServiceAccountKeyCreation. Bitten Sie einen Administrator, die Schlüsselerstellung für dieses Projekt zu erlauben, oder legen Sie das Projekt unter einem privaten Google-Konto an — die Tabelle lässt sich mit dem Service-Account dieses Projekts teilen, ganz gleich, wem die Tabelle gehört.
„Google Sheets API has not been used in project … or it is disabled": Die API ist in dem Projekt, das den Schlüssel ausgestellt hat, nicht aktiviert (Schritt 2) — aktivieren Sie sie dort, nicht in einem anderen Projekt. Eine frisch aktivierte API kann einige Minuten brauchen, bis sie wirksam wird.
Schlüsseldatei nicht gefunden: Der Pfad enthält einen Tippfehler, oder Unity wurde gestartet, bevor die Umgebungsvariable existierte — setzen Sie die Variable, und starten Sie dann Unity und Unity Hub neu.
Schlüssel kompromittiert oder verloren: Löschen Sie ihn im Tab Keys des Service-Accounts, erstellen Sie einen neuen JSON-Schlüssel und ersetzen Sie die Datei. Alles andere bleibt unverändert — die E-Mail-Adresse und die Tabellenfreigabe bleiben gültig.