Zum Inhalt springen
Saiku Cloud

Ein BigQuery-Warehouse verbinden

Diese Anleitung führt Sie durch das Verbinden eines Google-BigQuery-Datensatzes mit Saiku Cloud. Fünfzehn Minuten, wenn Sie bereits einen Service Account haben; dreißig, wenn Sie auch einen in IAM erstellen müssen.

Plan-Auswirkung: Jeder Saiku-Cloud-Plan unterstützt BigQuery-BYOC.

Treiber: Saiku Cloud liefert Googles offiziellen BigQuery-JDBC-Treiber (Apache 2.0, ~56 MB shaded). Die Auth läuft über einen Service-Account-JSON-Key — es gibt keinen passwortbasierten Auth-Pfad.

Was Sie brauchen

  • Ein Google-Cloud-Projekt mit aktiviertem BigQuery.
  • Einen Datensatz innerhalb dieses Projekts, in dem Ihre Analytics-Daten liegen.
  • IAM-Owner oder gleichwertige Berechtigung, um einen Service Account zu erstellen.

Schritt 1 — Netzwerkzugriff (gute Nachricht)

Die API von BigQuery ist ein von Google verwalteter Service, der von jedem mit dem Internet verbundenen Host erreichbar ist. Keine Firewall-Allowlist erforderlich. Die Egress-IP von Saiku Cloud (87.99.153.244) ist eine von vielen, die die BigQuery-API treffen werden; Googles Edge übernimmt das Routing transparent.

Weiter zu Schritt 2.

Schritt 2 — Einen Read-only-Service-Account erstellen

Saiku Cloud benötigt BigQuery Data Viewer (für SELECT) + BigQuery Job User (für Query-Ausführung).

In der Google-Cloud-Konsole:

  1. IAM & Admin → Service Accounts → Service Account erstellen.

  2. Name: saiku-read. Beschreibung: Saiku Cloud read-only access.

  3. Rollen gewähren:

    • BigQuery Data Viewer — scopen Sie ihn auf bestimmte Datensätze, wenn Sie strengeren Zugriff möchten (Data Viewer auf Projekt-Scope liest alle Datensätze; auf Dataset-Scope liest nur diesen einen).
    • BigQuery Job User — muss auf Projekt-Scope liegen (BigQuery unterstützt keinen Dataset-scoped Job User).

  4. Klicken Sie in den erstellten Service Account → Keys → Key hinzufügen → Neuen Key erstellen → JSON. Der Browser lädt eine <project>-<id>.json-Datei herunter.

  5. Dies ist das Credential — speichern Sie es in Ihrem Passwort-Manager. Es enthält den privaten Schlüssel.

Schritt 3 — Die JDBC-URL bauen

Die Form (semikolon-getrennt, NICHT Querystring):

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=<PROJECT>;OAuthType=0;OAuthServiceAcctEmail=<SA_EMAIL>;OAuthPvtKey=<INLINE_PEM>;DefaultDataset=<DATASET>

Konkretes Beispiel mit Inline-PEM:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-analytics-prod;OAuthType=0;OAuthServiceAcctEmail=saiku-read@my-analytics-prod.iam.gserviceaccount.com;OAuthPvtKey=-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEF...-----END PRIVATE KEY-----;DefaultDataset=analytics

Parameter-Map:

  • https://www.googleapis.com/bigquery/v2:443 — der API-Endpunkt. Immer dieser für den öffentlichen BigQuery-Service. Private-Service-Connect-Endpunkte haben eine andere Form (siehe Enterprise: privates Netzwerk).
  • ProjectId= — Ihre Google-Cloud-Projekt-ID (die alphanumerische aus der Konsolen-URL, nicht der Projektname).
  • OAuthType=0 — Service-Account-Key-Auth. Andere Werte: 1 (User-OAuth — nicht in Saiku unterstützt), 3 (Application Default Credentials — funktioniert nur, wenn die Engine Zugriff auf ADC hat, was im cloud-gehosteten Saiku-Cloud-Deployment generell nicht zutrifft).
  • OAuthServiceAcctEmail= — die E-Mail des Service Accounts, kopiert aus Schritt 2.4. Format: <saname>@<project>.iam.gserviceaccount.com.
  • OAuthPvtKeyPath= ODER OAuthPvtKey= — eins von beiden.
    • OAuthPvtKeyPath=/path/to/key.json — der Treiber liest die Datei zur Laufzeit. Funktioniert auf dem cloud-gehosteten Saiku Cloud nicht, weil Sie keine Dateien auf dem Dateisystem des Engine-Containers ablegen können.
    • OAuthPvtKey=<inline PEM> — der wörtliche -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY------Inhalt aus dem private_key-Feld des JSON-Keys, mit wörtlichem \n zwischen Zeilen. Verwenden Sie dies für Cloud-gehostet.
  • DefaultDataset= — der BigQuery-Datensatz (der zweite Abschnitt von project.dataset.table). Erlaubt es Schemas, auf unqualifizierte Tabellennamen zu verweisen wie <Table name='sales'/>, statt jeden Verweis voll zu qualifizieren. Erforderlich, damit BYOC-Schemas durch Saiku Clouds Mondrian laden (die Metadaten-API des Treibers löst unqualifizierte Tabellen nur auf, wenn dies gesetzt ist).

Cube-Authoring-Seite: Schema-/Catalog-Properties für Metadaten-Introspection

Wenn Sie eine Mondrian-Schema-XML über Saiku Cloud hochladen, die unqualifizierte BigQuery-Tabellen referenziert (z. B. <Table name='salary'/> nicht <Table name='salary' schema='analytics'/>), muss Saiku Cloud auch den Datensatz und das Projekt für die JDBC-Metadaten-Introspection kennen. Diese werden als Connect-String-Properties auf der Mondrian-Wrapper-Ebene zusätzlich zur obigen URL übergeben:

  • JdbcSchema=<dataset> — derselbe Wert wie DefaultDataset= in der URL.
  • JdbcCatalog=<project> — derselbe Wert wie ProjectId= in der URL.

Der Connection-Wizard von Saiku Cloud leitet diese automatisch aus den ProjectId=- und DefaultDataset=-Parametern der URL ab, wenn Sie die Verbindung speichern, sodass die meisten Kunden sie nie sehen. Hier erwähnt, weil die .sds-Form der Engine auf der Platte sie enthält und sie in Audit-Logs auftauchen:

jdbc:mondrian:Jdbc='jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-analytics-prod;OAuthType=0;OAuthServiceAcctEmail=...;OAuthPvtKey=...;DefaultDataset=analytics';Catalog=file:/var/lib/saiku/data/<your-schema>.xml;JdbcDrivers=com.google.cloud.bigquery.jdbc.BigQueryDriver;JdbcSchema=analytics;JdbcCatalog=my-analytics-prod

Diese beiden Anforderungen sind detailliert in den BigQuery-Mondrian-Notizen mit dem Fehlerkatalog dokumentiert.

Extraktion des privaten Schlüssels aus dem JSON

Das in Schritt 2 heruntergeladene JSON sieht so aus:

{
  "type": "service_account",
  "project_id": "...",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n",
  "client_email": "...",
  ...
}

Ziehen Sie den private_key-Wert heraus, entfernen Sie die umschließenden Anführungszeichen, und das ist, was in OAuthPvtKey= geht (die \n-Escapes sind wörtlich — behalten Sie sie als Backslash-n-Strings, NICHT als tatsächliche Zeilenumbrüche).

Schritt 4 — Verbinden über den Saiku-Cloud-Wizard

  1. Melden Sie sich bei https://cloud.saiku.bi/ an.

  2. Navigieren Sie zu Verbindungen in der linken Seitenleiste.

  3. Klicken Sie unter 1. Warehouse-Typ wählen auf das BigQuery-Kachel.

  4. Füllen Sie aus:

    • JDBC-URL — die URL aus Schritt 3.
    • Benutzername — beliebig (z. B. bigquery). Der Treiber ignoriert dieses Feld; die Auth ist in der URL.
    • Passwort — beliebig, nicht leer (z. B. unused-key-in-url). Wird ebenfalls ignoriert.

  5. Klicken Sie auf Verbindung testen.

Erwarten Sie einen grünen Ergebnis-Banner: ✓ Connection successful plus die erkannte BigQuery-Version (etwa BigQuery 2.0). Die erste BigQuery-Verbindung dauert 5–10 Sekunden (Token-Austausch + Dataset-Auflistung).

Schritt 5 — Die Verbindung speichern

Gleiche Form wie bei jedem anderen Dialekt — geben Sie das Platzhalter-Passwort erneut ein, geben Sie ihr ein Label, speichern Sie.

Fehlerbehebung

✗ Connection failed (AUTH_FAILED)

  • OAuthPvtKey-Formatierung — häufigste Ursache. Das PEM muss wörtliche \n zwischen Zeilen enthalten (NICHT echte Zeilenumbrüche). Doppelt prüfen: Der Wert sollte mit -----BEGIN PRIVATE KEY-----\nMIIE... beginnen (Backslash-n, kein Zeilenumbruch).
  • Service Account hat kein BigQuery Job User auf Projekt-Scope — selbst mit Data Viewer auf dem Dataset lehnt BigQuery Queries von Accounts ohne projektweiten Job User ab.
  • Service Account deaktiviert oder gelöscht — prüfen Sie die IAM-Konsole.

✗ Connection failed (DATABASE_NOT_FOUND)

ProjectId= ist falsch, oder der Service Account hat keine sichtbaren Datensätze in diesem Projekt. Verifizieren Sie, dass die Projekt-ID dem entspricht, was in der Konsolen-URL von Google Cloud angezeigt wird.

✗ Connection failed (HOST_UNREACHABLE) oder (TIMEOUT)

Die BigQuery-API ist selten unerreichbar; prüfen Sie die GCP-Statusseite. Wenn GCP gesund ist, ist das URL-Segment https://www.googleapis.com/bigquery/v2:443 wahrscheinlich falsch getippt — es muss exakt sein.

✗ Connection failed with "OAuthType=1 requires interactive OAuth"

Sie haben OAuthType=1 (User-OAuth) statt OAuthType=0 (Service-Account) gesetzt. Wechseln Sie zu OAuthType=0 und stellen Sie einen Service-Account-Key bereit.

Cube rendert, aber ohne Daten

Der Service Account hat BigQuery Job User (also gelingen Queries), aber kein BigQuery Data Viewer auf dem Dataset (also liefern Queries leere Ergebnisse). Fügen Sie Data Viewer auf Dataset-Scope hinzu.

Alles andere

Machen Sie einen Screenshot des Wizards mit sichtbarem rotem Ergebnis-Banner (Kind: ...-Zeile insbesondere) und senden Sie ihn an support@saiku.bi.

Enterprise: privates Netzwerk {#enterprise-privates-netzwerk}

Für Enterprise-Kunden unterstützt BigQuery Private Service Connect — der BigQuery-API-Traffic Ihres Tenants bleibt innerhalb eines privaten Netzwerks. Der JDBC-URL-Endpunkt ändert sich von https://www.googleapis.com/bigquery/v2:443 zu Ihrem PSC-Endpunkt. Kontaktieren Sie Ihr Account-Team, um das Peering bereitzustellen.

Mit FoodMart ausprobieren

Möchten Sie Saiku Cloud mit diesem Dialekt testen, bevor Sie Ihre eigenen Daten verbinden? Laden Sie den FoodMart-Sample-Datensatz, gepackt für BigQuery, herunter:

FoodMart-Sample-Datensatz für BigQuery