BigQuery-Abos erstellen

In diesem Dokument wird beschrieben, wie Sie ein BigQuery-Abo erstellen. Sie können ein BigQuery-Abo mit der Google Cloud Console, der Google Cloud CLI, der Clientbibliothek oder der Pub/Sub API erstellen.

Hinweise

Bevor Sie dieses Dokument lesen, sollten Sie mit Folgendem vertraut sein:

• Weitere Informationen zu Abos

• Der Workflow für BigQuery-Abos

• Informationen zum Konfigurieren eines Themas für unzustellbare Nachrichten, um Nachrichtenfehler zu behandeln.

Neben Ihrer Vertrautheit mit Pub/Sub und Voraussetzungen für BigQuery erfüllen bevor Sie ein BigQuery-Abo erstellen:

• Eine BigQuery-Tabelle ist vorhanden. Alternativ können Sie auch eines erstellen wenn Sie das BigQuery-Abo erstellen, wie in weiter unten in diesem Dokument.

• Kompatibilität zwischen dem Schema des Pub/Sub-Themas und in der BigQuery-Tabelle. Wenn Sie ein nicht kompatibles wird ein Kompatibilitätsfehler angezeigt, . Weitere Informationen finden Sie unter Schemakompatibilität.

Erforderliche Rollen und Berechtigungen

Im Folgenden finden Sie eine Liste mit Richtlinien in Bezug auf Rollen und Berechtigungen:

• Zum Erstellen eines Abos müssen Sie die Zugriffssteuerung im Projekt konfigurieren

• Außerdem benötigen Sie Berechtigungen auf Ressourcenebene, Abos und Themen befinden sich in verschiedenen Projekten, wie später erläutert wird. in diesem Abschnitt.

• Zum Erstellen eines BigQuery-Abos Das Pub/Sub-Dienstkonto muss die Berechtigung zum Schreiben in den bestimmte BigQuery-Tabelle. Weitere Informationen zur diese Berechtigungen zu erteilen, finden Sie im nächsten Abschnitt dieses Dokuments.

• Sie können ein BigQuery-Abo in einem Projekt konfigurieren um in eine BigQuery-Tabelle in einem anderen Projekt zu schreiben.

Um die Berechtigungen zu erhalten, die Sie zum Erstellen von BigQuery-Abos benötigen, bitten Sie Ihren Administrator, Ihnen IAM-Rolle Pub/Sub-Bearbeiter (roles/pubsub.editor) für das Projekt. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält Berechtigungen, die zum Erstellen von BigQuery-Abos erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Wenn Sie BigQuery erstellen müssen Abos in einem Projekt, die mit einem Thema in einem anderen verknüpft sind Projekt enthalten ist, bitten Sie Ihren Themenadministrator, Ihnen auch den Pub/Sub Editor zu gewähren. Die IAM-Rolle (roles/pubsub.editor) für das Thema.

Pub/Sub-Dienstkonto BigQuery-Rollen zuweisen

Einige Google Cloud-Dienste haben von Google Cloud verwaltete Dienstkonten, mit denen die Dienste auf Ihre Ressourcen zugreifen können. Diese Dienstkonten werden als Dienst-Agents bezeichnet. Pub/Sub erstellt und verwaltet für jedes Projekt ein Dienstkonto im Format service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com.

Zum Erstellen eines BigQuery-Abos Dienstkonto muss über Schreibberechtigung verfügen an die spezifische BigQuery-Tabelle an und lesen die Metadaten der Tabelle.

Weisen Sie dem Pub/Sub-Dienstkonto die Rolle „BigQuery-Datenbearbeiter“ (roles/bigquery.dataEditor) zu.

1. Öffnen Sie in der Google Cloud Console die Seite IAM.

   IAM aufrufen

2. Klicken Sie auf Zugriff erlauben.

3. Geben Sie im Bereich Hauptkonten hinzufügen den Namen Ihres Pub/Sub-Dienstkontos ein. Das Dienstkonto hat das Format service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com. Bei einem Projekt mit project-number=112233445566 hat das Dienstkonto beispielsweise das Format service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com.

4. Klicken Sie im Bereich Rollen zuweisen auf Weitere Rolle hinzufügen.

5. Geben Sie im Drop-down-Menü Rolle auswählen die Zahl BigQuery ein und wählen Sie die Rolle BigQuery-Datenbearbeiter aus.

6. Klicken Sie auf Speichern.

Weitere Informationen zu BigQuery IAM Siehe BigQuery-Rollen und -Berechtigungen.

BigQuery-Aboeigenschaften

Wenn Sie ein BigQuery-Abo konfigurieren, können Sie die folgenden Eigenschaften angeben.

Allgemeine Eigenschaften

Weitere Informationen zu allgemeinen Abo-Properties das Sie für alle Abos festlegen können.

Schema des Themas verwenden

Mit dieser Option kann Pub/Sub das Schema des Pub/Sub-Themas verwenden, an das das Abo angehängt ist. Außerdem kann Pub/Sub schreibt die Felder in Nachrichten in den entsprechenden Spalten in der BigQuery-Tabelle.

Beachten Sie bei der Verwendung dieser Option die folgenden zusätzlichen Anforderungen:

• Die Felder im Schema des Themas und im BigQuery-Schema müssen dieselben Namen haben und ihre Typen müssen miteinander kompatibel sein.

• Alle optionalen Felder im Schema des Themas müssen auch im BigQuery-Schema optional sein.

• Pflichtfelder im Schema des Themas müssen nicht im BigQuery-Schema erforderlich.

• Wenn es BigQuery-Felder gibt, die nicht im Themaschema vorhanden sind, müssen diese BigQuery-Felder im Modus NULLABLE sein.

• Wenn das Themaschema zusätzliche Felder enthält, die nicht im BigQuery-Schema vorhanden sind und gelöscht werden können, wählen Sie die Option Unbekannte Felder löschen aus.

• Sie können nur eine der Aboeigenschaften auswählen: Themaschema verwenden oder Tabellenschema verwenden.

Wenn Sie die Option Schema des Themas verwenden oder Tabellenschema verwenden nicht auswählen, muss die BigQuery-Tabelle eine Spalte namens data vom Typ BYTES, STRING oder JSON haben. Pub/Sub schreibt die Nachricht in diese BigQuery-Spalte.

Änderungen am Pub/Sub-Themenschema oder am BigQuery-Tabellenschema werden möglicherweise nicht sofort wirksam, wenn Nachrichten in die BigQuery-Tabelle geschrieben werden. Wenn zum Beispiel die Drop-down- unbekannte Felder aktiviert und ein Feld in der Pub/Sub-Schema, aber nicht das BigQuery-Schema, Nachrichten, die in die BigQuery-Tabelle geschrieben wurden, enthalten möglicherweise nachdem es dem BigQuery-Schema hinzugefügt wurde. Schließlich Die Schemasynchronisierung und nachfolgende Nachrichten enthalten das Feld.

Wenn Sie die Option Schema des Themas verwenden für Ihre BigQuery-Datei verwenden können Sie auch die Vorteile der BigQuery-Änderung Data Capture (CDC). CDC aktualisiert Ihre BigQuery-Tabellen verarbeitet und Änderungen auf vorhandene Zeilen angewendet.

Weitere Informationen zu dieser Funktion finden Sie unter Tabellenaktualisierungen mit Change Data Capture streamen.

Informationen zur Verwendung dieser Funktion mit BigQuery-Abos finden Sie unter BigQuery-Change Data Capture.

Schema der Tabelle verwenden

Mit dieser Option kann Pub/Sub das Schema des BigQuery-Tabelle zum Schreiben der Felder einer JSON-Datei in die entsprechenden Spalten ein. Beachten Sie bei Verwendung dieser Option die folgenden zusätzlichen Anforderungen:

• Veröffentlichte Nachrichten müssen im JSON-Format vorliegen.

• Die folgenden JSON-Konvertierungen werden unterstützt:

  JSON-Typ	BigQuery-Datentyp
  string	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME oder TIMESTAMP
  number	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME oder TIMESTAMP

  • Wenn Sie number bis DATE, DATETIME, TIME oder TIMESTAMP-Conversions verwenden, muss die Zahl den unterstützten Darstellungen entsprechen.
  • Wenn Sie die Konvertierung von number in NUMERIC oder BIGNUMERIC verwenden, sind die Genauigkeit und der Wertebereich auf die vom IEEE 754-Standard für Gleitkommaarithmetik akzeptierten Werte beschränkt. Wenn Sie eine hohe Genauigkeit oder einen größeren Wertebereich benötigen, verwenden Sie stattdessen string bis NUMERIC oder BIGNUMERIC-Conversions.
  • Bei der Verwendung von string- bis NUMERIC- oder BIGNUMERIC-Konvertierungen geht Pub/Sub davon aus, dass der String eine für Menschen lesbare Zahl ist (z. B. "123.124"). Wenn die Verarbeitung des Strings als für Menschen lesbare Zahl fehlschlägt, behandelt Pub/Sub den String als mit dem BigDecimalByteStringEncoder codierte Bytes.

• Wenn das Thema des Abos ein Schema verknüpft hat, dann Die Eigenschaft für die Nachrichtencodierung muss auf JSON festgelegt sein.

• Wenn es BigQuery-Felder gibt, die in müssen diese BigQuery-Felder im Modus NULLABLE sein.

• Wenn die Nachrichten zusätzliche Felder enthalten, die nicht im BigQuery-Schema vorhanden sind und gelöscht werden können, wählen Sie die Option Unbekannte Felder löschen aus.

• Sie können nur eine der Abo-Properties auswählen: Schema des Themas verwenden oder Tabellenschema verwenden.

Wenn Sie die Option Schema des Themas verwenden oder Tabellenschema verwenden nicht auswählen, dass die BigQuery-Tabelle eine Spalte mit dem Namen data Geben Sie BYTES, STRING oder JSON ein. Pub/Sub schreibt die Nachricht in diese BigQuery-Spalte.

Änderungen am BigQuery-Tabellenschema werden bei Nachrichten, die in die BigQuery-Tabelle geschrieben werden, möglicherweise nicht sofort wirksam. Wenn beispielsweise die Option Unbekannte Felder löschen aktiviert ist und ein Feld in den Nachrichten, aber nicht im BigQuery-Schema vorhanden ist, enthalten Nachrichten, die in die BigQuery-Tabelle geschrieben werden, das Feld möglicherweise auch dann nicht, wenn es dem BigQuery-Schema hinzugefügt wurde. Schließlich wird das Schema synchronisiert und nachfolgende Nachrichten enthalten das Feld.

Wenn Sie für Ihr BigQuery-Abo die Option Tabellenschema verwenden verwenden, können Sie auch BigQuery Change Data Capture (CDC) nutzen. CDC aktualisiert Ihre BigQuery-Tabellen durch Verarbeitung und Anwendung von Änderungen auf vorhandene Zeilen.

Weitere Informationen zu dieser Funktion finden Sie unter Tabellenaktualisierungen mit Change Data Capture streamen.

Informationen zur Verwendung dieser Funktion mit BigQuery-Abos finden Sie unter BigQuery-Change Data Capture.

Unbekannte Felder löschen

Diese Option wird mit der Option Schema des Themas verwenden oder Schema der Tabelle verwenden verwendet. Mit dieser Option kann Pub/Sub jedes im Thema vorhandene Feld löschen Schema oder Nachricht, aber nicht im BigQuery-Schema. Wenn Unbekannte Felder löschen nicht festgelegt ist, werden Nachrichten mit zusätzlichen Feldern nicht in BigQuery geschrieben und verbleiben im Rückstand des Abos. Das Abo befindet sich dann im Fehlerstatus.

Metadaten schreiben

Mit dieser Option kann Pub/Sub die Metadaten jeder Nachricht in zusätzliche Spalten in der BigQuery-Tabelle schreiben. Andernfalls sind die Metadaten nicht in die BigQuery-Tabelle geschrieben.

Wenn Sie die Option Metadaten schreiben auswählen, muss die BigQuery-Tabelle die in der folgenden Tabelle beschriebenen Felder enthalten.

Wenn Sie die Option Metadaten schreiben nicht auswählen, ist für die BigQuery-Zieltabelle nur das Feld data erforderlich, es sei denn, use_topic_schema ist wahr. Wenn Sie sowohl Metadaten schreiben als auch Schemaoptionen des Themas verwenden, muss das Schema des Themas dürfen keine Felder enthalten, deren Namen mit denen der Metadatenparameter übereinstimmen. Diese Einschränkung gilt auch für CamelCase-Versionen dieser Parameter.

BigQuery-Abo erstellen

Die folgenden Beispiele zeigen, wie Sie ein Abo mit BigQuery-Zustellung erstellen.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& table_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_bigquery_config()->set_table(table_id);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

using Google.Cloud.PubSub.V1;

public class CreateBigQuerySubscriptionSample
{
    public Subscription CreateBigQuerySubscription(string projectId, string topicId, string subscriptionId, string bigqueryTableId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            BigqueryConfig = new BigQueryConfig
            {
                Table = bigqueryTableId
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

// createBigQuerySubscription creates a Pub/Sub subscription that exports messages to BigQuery.
func createBigQuerySubscription(w io.Writer, projectID, subID string, topic *pubsub.Topic, table string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// table := "my-project-id.dataset_id.table_id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic: topic,
		BigQueryConfig: pubsub.BigQueryConfig{
			Table:         table,
			WriteMetadata: true,
		},
	})
	if err != nil {
		return fmt.Errorf("client.CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created BigQuery subscription: %v\n", sub)

	return nil
}

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.BigQueryConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateBigQuerySubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bigqueryTableId = "your-project.your-dataset.your-table";

    createBigQuerySubscription(projectId, topicId, subscriptionId, bigqueryTableId);
  }

  public static void createBigQuerySubscription(
      String projectId, String topicId, String subscriptionId, String bigqueryTableId)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      BigQueryConfig bigqueryConfig =
          BigQueryConfig.newBuilder().setTable(bigqueryTableId).setWriteMetadata(true).build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setBigqueryConfig(bigqueryConfig)
                  .build());

      System.out.println("Created a BigQuery subscription: " + subscription.getAllFields());
    }
  }
}

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId,
  subscriptionNameOrId,
  bigqueryTableId
) {
  const options = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
  bigqueryTableId: string
) {
  const options: CreateSubscriptionOptions = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

use Google\Cloud\PubSub\PubSubClient;
use Google\Cloud\PubSub\V1\BigQueryConfig;

/**
 * Creates a Pub/Sub BigQuery subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $table      The BigQuery table to which to write.
 */
function create_bigquery_subscription($projectId, $topicName, $subscriptionName, $table)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = new BigQueryConfig(['table' => $table]);
    $subscription->create([
        'bigqueryConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "your-project.your-dataset.your-table"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

bigquery_config = pubsub_v1.types.BigQueryConfig(
    table=bigquery_table_id, write_metadata=True
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "bigquery_config": bigquery_config,
        }
    )

print(f"BigQuery subscription created: {subscription}.")
print(f"Table for subscription is: {bigquery_table_id}")

require "google/cloud/pubsub"

##
# Shows how to create a BigQuery subscription where messages published
# to a topic populates a BigQuery table.
#
# @param project_id [String]
# Your Google Cloud project (e.g. "my-project")
# @param topic_id [String]
# Your topic name (e.g. "my-secret")
# @param subscription_id [String]
# ID for new subscription to be created (e.g. "my-subscription")
# @param bigquery_table_id [String]
# ID of bigquery table (e.g "my-project:dataset-id.table-id")
#
def pubsub_create_bigquery_subscription project_id:, topic_id:, subscription_id:, bigquery_table_id:
  pubsub = Google::Cloud::Pubsub.new project_id: project_id
  topic = pubsub.topic topic_id
  subscription = topic.subscribe subscription_id,
                                 bigquery_config: {
                                   table: bigquery_table_id,
                                   write_metadata: true
                                 }
  puts "BigQuery subscription created: #{subscription_id}."
  puts "Table for subscription is: #{bigquery_table_id}"
end

BigQuery-Abo überwachen

Cloud Monitoring bietet eine Reihe von Messwerten, Abos überwachen.

Eine Liste aller verfügbaren Messwerte im Zusammenhang mit Pub/Sub und deren Beschreibungen Monitoring-Dokumentation für Pub/Sub

Sie können Abos auch in Pub/Sub überwachen.

Nächste Schritte

• Erstellen oder ändern Sie ein Abo mit gcloud-Befehlen.
• Mit REST APIs ein Abo erstellen oder ändern
• Fehlerbehebung bei einem BigQuery-Abo