Esportare messaggi Pub/Sub Lite in Pub/Sub

Questo documento descrive come configurare l'esportazione automatica di di messaggi Pub/Sub Lite in Pub/Sub.

Ecco alcuni scenari in cui è possibile utilizzare questa funzionalità:

  • Interoperabilità tra carichi di lavoro che utilizzano una combinazione di Pub/Sub Lite e Pub/Sub.
  • Esegui la migrazione di un carico di lavoro Pub/Sub Lite a Pub/Sub.
  • Usa le funzionalità avanzate di Pub/Sub, come le sottoscrizioni push e di un'applicazione esistente basata su in Pub/Sub Lite.
  • Consolidare più pipeline di dati.

Panoramica

Per esportare i messaggi da Pub/Sub Lite a Pub/Sub: crei un tipo speciale di sottoscrizione chiamato sottoscrizione per l'esportazione. Un la sottoscrizione Export riceve messaggi da un argomento Lite, li converte in Pub/Sub e invia i messaggi convertiti a un relativo all'argomento Pub/Sub di destinazione.

Diagramma dell'esportazione di messaggi Pub/Sub Lite

Un argomento Lite può avere una combinazione sia di sottoscrizioni di esportazione che di abbonamenti. I due tipi di abbonamento sono identici in termini di utilizzo della quota e throughput delle prenotazioni. Un abbonamento di esportazione consumerà la capacità di velocità effettiva dell'abbonamento Lite e verrà addebitato il costo della velocità effettiva di pubblicazione di Pub/Sub.

Una sottoscrizione di esportazione collega un argomento Lite a esattamente uno Pub/Sub. Tuttavia, un argomento Lite può avere più sottoscrizioni di esportazione che si connettono a diversi argomenti Pub/Sub (architettura a ventaglio). Puoi anche esportare da più argomenti Lite allo stesso argomento Pub/Sub (architettura fan-in).

Autenticazione

Una sottoscrizione di esportazione accede sia a Pub/Sub Lite delle risorse Pub/Sub. Per creare una sottoscrizione di esportazione, devi disporre delle seguenti autorizzazioni:

  • pubsublite.subscriptions.create. I seguenti ruoli predefiniti contengono autorizzazione:

    • roles/pubsublite.admin
    • roles/pubsublite.editor

    Vedi Controllo dell'accesso per Pub/Sub Lite.

  • pubsub.topics.get. I seguenti ruoli predefiniti contengono questa autorizzazione:

    • roles/pubsub.admin
    • roles/pubsub.editor
    • roles/pubsub.viewer

    Consulta Controllo dell'accesso per Pub/Sub.

Agenti di servizio

Una sottoscrizione di esportazione viene pubblicata in un argomento Pub/Sub sul tuo per conto tuo. Per farlo, utilizza un agente di servizio.

Dopo aver creato la prima sottoscrizione di esportazione in un progetto, viene creato automaticamente un agente di servizio Pub/Sub Lite. Se sottoscrizioni di esportazione aggiuntive nello stesso progetto, utilizzano lo stesso dell'agente di servizio di servizio di Google Cloud. L'agente di servizio ha il seguente schema di denominazione: service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com.

L'agente di servizio viene creato con le autorizzazioni per pubblicare in tutti gli argomenti Pub/Sub e Pub/Sub Lite nello stesso progetto della sottoscrizione di esportazione. Se l'argomento Pub/Sub di destinazione si trova in un progetto diverso dall'abbonamento di esportazione, devi concedere all'agente di servizio autorizzazioni aggiuntive aggiungendo il ruolo Publisher Pub/Sub (roles/pubsub.publisher). Puoi concedere autorizzazioni per un intero progetto o per un singolo argomento. Consigliamo di concedere le autorizzazioni a livello di argomento, seguendo il principio del privilegio minimo.

Per ulteriori informazioni, vedi Controllo dell'accesso tramite la console Google Cloud Puoi anche utilizzare il comando gcloud projects add-iam-policy-binding per aggiungere i ruoli IAM:

gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
 --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com
 --role=roles/pubsub.publisher

Sostituisci quanto segue:

  • TOPIC_NAME: il nome dell'argomento Pub/Sub di destinazione per aggiungere il vincolo del criterio IAM.
  • PROJECT_NUMBER: il numero del progetto Progetto di esportazione della sottoscrizione Pub/Sub Lite.

Crea una sottoscrizione per l'esportazione

Puoi creare un abbonamento di esportazione Lite con la console Google Cloud, Google Cloud CLI o l'API Pub/Sub Lite.

Una sottoscrizione di esportazione Lite deve trovarsi nello stesso progetto e nella stessa località di Lite dall'argomento a cui è allegato. Per creare l'argomento Lite, consulta Creare e gestire gli argomenti Lite.

Se colleghi un abbonamento di esportazione a un argomento Lite, assicurati che tutti i messaggi pubblicati nell'argomento Lite siano compatibili con Pub/Sub. Per ulteriori informazioni, consulta la sezione Compatibilità dei messaggi.

Una volta creata, non puoi modificare una sottoscrizione per l'esportazione in un abbonamento standard e viceversa.

Console

  1. Vai alla pagina Abbonamenti Lite.

    Vai agli abbonamenti Lite

  2. Fai clic su Crea sottoscrizione Lite.

  3. Inserisci un ID abbonamento Lite.

  4. Seleziona un argomento Lite da cui ricevere messaggi.

  5. Seleziona Recapita i messaggi immediatamente o Recapita i messaggi dopo archiviati.

  6. Scegli un tipo di Offset iniziale.

  7. Seleziona Esporta in argomento Pub/Sub.

  8. Nell'elenco Argomento di destinazione, scegli un argomento Pub/Sub per ricevere i messaggi Lite esportati.

  9. Facoltativo. Specifica un argomento messaggi non recapitabili.

    1. Seleziona la casella di controllo Attiva messaggi non recapitabili.
    2. Seleziona un argomento Lite da utilizzare come argomento messaggi non recapitabili o fai clic su Crea Argomento Lite per creare un nuovo argomento messaggi non recapitabili. L'argomento della posta inutilizzata deve trovarsi nella stessa posizione (zona o regione) e nello stesso progetto della sottoscrizione di esportazione.

  10. Fai clic su Crea.

gcloud

Per creare una sottoscrizione per l'esportazione, utilizza gcloud pubsub lite-subscriptions create :

gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \
  --location=LOCATION \
  --topic=TOPIC_ID \
  --export-pubsub-topic=PUBSUB_TOPIC_NAME \
  --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
  --export-desired-state=DESIRED_STATE

Sostituisci quanto segue:

  • SUBSCRIPTION_ID: l'ID dell'abbonamento Lite da creare.
  • LOCATION: la località dell'abbonamento Lite.
  • TOPIC_ID: l'ID dell'argomento Lite da collegare all'abbonamento Lite.
  • PUBSUB_TOPIC_NAME: il nome dell'argomento Pub/Sub in esporta in. Specifica il nome completo se l'argomento si trova in un altro progetto: projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID: facoltativo. L'ID di un argomento Lite da utilizzare come argomento messaggi non recapitabili. L'argomento messaggi non recapitabili deve essere in la stessa località (zona o regione) e lo stesso progetto della sottoscrizione di esportazione.
  • DESIRED_STATE: facoltativo. Lo stato iniziale dell'abbonamento. Sono supportati i seguenti valori:
    • active: la sottoscrizione esporta i messaggi Lite in in Pub/Sub. (opzione predefinita).
    • paused: l'esportazione dei messaggi Lite è sospesa.

Se la richiesta va a buon fine, la riga di comando mostra una conferma:

Created [SUBSCRIPTION_ID].

Protocollo

Per creare un abbonamento per l'esportazione Lite, invia una richiesta POST come la seguente:

POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

Sostituisci quanto segue:

  • REGION: la regione in cui archiviare l'abbonamento Lite.
  • PROJECT_NUMBER: il numero del progetto in cui creare l'abbonamento Lite.
  • LOCATION: il nome di una località supportata da Pub/Sub Lite.
  • SUBSCRIPTION_ID: l'ID dell'abbonamento Lite.

Specifica i seguenti campi nel corpo della richiesta:

{
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Sostituisci quanto segue:

  • DELIVERY_REQUIREMENT: il requisito di recapito, DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
  • DESIRED_STATE: lo stato iniziale dell'abbonamento. Sono supportati i seguenti valori:
    • ACTIVE: la sottoscrizione esporta i messaggi Lite in in Pub/Sub.
    • PAUSED: l'esportazione dei messaggi Lite è sospesa.
  • DEAD_LETTER_TOPIC_ID: l'ID di un argomento Lite esistente da utilizzare come argomento non recapitabile. L'argomento deve essere nello stesso località (zona o regione) e progetto come abbonamento per l'esportazione.
  • PUBSUB_TOPIC_NAME: il nome dell'argomento Pub/Sub in esporta in. Formato di esempio: projects/my-project-id/topics/my-topic-id.

Se la richiesta ha esito positivo, la risposta è la sottoscrizione Lite in JSON formato:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      },
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go. 

import (
	"context"
	"fmt"
	"io"

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

func createPubsubExportSubscription(w io.Writer, projectID, region, location, topicID, subID, pubsubTopicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// NOTE: location can be either a region ("us-central1") or a zone ("us-central1-a")
	// For a list of valid locations, see https://cloud.google.com/pubsub/lite/docs/locations.
	// location := "us-central1"
	// NOTE: topic and subscription must be in the same region/zone (e.g. "us-central1-a")
	// topicID := "my-topic"
	// subID := "my-subscription"
	// pubsubTopicID := "destination-topic-id"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %w", err)
	}
	defer client.Close()

	// Initialize the subscription to the oldest retained messages for each
	// partition.
	targetLocation := pubsublite.AtTargetLocation(pubsublite.Beginning)

	sub, err := client.CreateSubscription(ctx, pubsublite.SubscriptionConfig{
		Name:                fmt.Sprintf("projects/%s/locations/%s/subscriptions/%s", projectID, location, subID),
		Topic:               fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, location, topicID),
		DeliveryRequirement: pubsublite.DeliverImmediately, // Can also be DeliverAfterStored.
		// Configures an export subscription that writes messages to a Pub/Sub topic.
		ExportConfig: &pubsublite.ExportConfig{
			DesiredState: pubsublite.ExportActive, // Can also be ExportPaused.
			Destination: &pubsublite.PubSubDestinationConfig{
				Topic: fmt.Sprintf("projects/%s/topics/%s", projectID, pubsubTopicID),
			},
		},
	}, targetLocation)
	if err != nil {
		return fmt.Errorf("client.CreateSubscription got err: %w", err)
	}
	fmt.Fprintf(w, "Created export subscription: %s\n", sub.Name)
	return nil
}

Java

Prima di eseguire questo esempio, segui le istruzioni di configurazione di Java riportate in Librerie client Pub/Sub Lite. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.BacklogLocation;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudRegionOrZone;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.SeekTarget;
import com.google.cloud.pubsublite.SubscriptionName;
import com.google.cloud.pubsublite.SubscriptionPath;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.ExportConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.PubSubConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.State;
import com.google.cloud.pubsublite.proto.Subscription;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig.DeliveryRequirement;
import java.util.concurrent.ExecutionException;

public class CreatePubsubExportSubscriptionExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String cloudRegion = "your-cloud-region";
    char zoneId = 'b';
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String pubsubTopicId = "destination-topic-id";
    long projectNumber = Long.parseLong("123456789");
    // True if using a regional location. False if using a zonal location.
    // https://cloud.google.com/pubsub/lite/docs/topics
    boolean regional = false;

    createPubsubExportSubscriptionExample(
        cloudRegion, zoneId, projectNumber, topicId, subscriptionId, pubsubTopicId, regional);
  }

  public static void createPubsubExportSubscriptionExample(
      String cloudRegion,
      char zoneId,
      long projectNumber,
      String topicId,
      String subscriptionId,
      String pubsubTopicId,
      boolean regional)
      throws Exception {

    CloudRegionOrZone location;
    if (regional) {
      location = CloudRegionOrZone.of(CloudRegion.of(cloudRegion));
    } else {
      location = CloudRegionOrZone.of(CloudZone.of(CloudRegion.of(cloudRegion), zoneId));
    }

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(location)
            .setName(TopicName.of(topicId))
            .build();

    SubscriptionPath subscriptionPath =
        SubscriptionPath.newBuilder()
            .setLocation(location)
            .setProject(ProjectNumber.of(projectNumber))
            .setName(SubscriptionName.of(subscriptionId))
            .build();

    com.google.pubsub.v1.TopicName pubsubTopicName =
        com.google.pubsub.v1.TopicName.of(String.valueOf(projectNumber), pubsubTopicId);

    Subscription subscription =
        Subscription.newBuilder()
            .setDeliveryConfig(
                // Possible values for DeliveryRequirement:
                // - `DELIVER_IMMEDIATELY`
                // - `DELIVER_AFTER_STORED`
                // You may choose whether to wait for a published message to be successfully written
                // to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
                // suitable for applications that need higher throughput.
                DeliveryConfig.newBuilder()
                    .setDeliveryRequirement(DeliveryRequirement.DELIVER_IMMEDIATELY))
            .setExportConfig(
                // Configures an export subscription that writes messages to a Pub/Sub topic.
                ExportConfig.newBuilder()
                    // Possible values for State:
                    // - `ACTIVE`: enable message processing.
                    // - `PAUSED`: suspend message processing.
                    .setDesiredState(State.ACTIVE)
                    .setPubsubConfig(
                        PubSubConfig.newBuilder().setTopic(pubsubTopicName.toString())))
            .setName(subscriptionPath.toString())
            .setTopic(topicPath.toString())
            .build();

    // Target location within the message backlog that the subscription should be initialized to.
    SeekTarget initialLocation = SeekTarget.of(BacklogLocation.BEGINNING);

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(location.extractRegion()).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources, or
    // use "try-with-close" statement to do this automatically.
    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Subscription response = adminClient.createSubscription(subscription, initialLocation).get();
      System.out.println(response.getAllFields() + " created successfully.");
    } catch (ExecutionException e) {
      try {
        throw e.getCause();
      } catch (AlreadyExistsException alreadyExists) {
        System.out.println("This subscription already exists.");
      } catch (Throwable throwable) {
        throwable.printStackTrace();
      }
    }
  }
}

Python

Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python in Librerie client Pub/Sub Lite. 

from google.api_core.exceptions import AlreadyExists
from google.cloud.pubsub_v1 import PublisherClient
from google.cloud.pubsublite import AdminClient, Subscription, ExportConfig
from google.cloud.pubsublite.types import (
    BacklogLocation,
    CloudRegion,
    CloudZone,
    SubscriptionPath,
    TopicPath,
)


def create_lite_pubsub_export_subscription(
    project_number,
    cloud_region="us-central1",
    zone_id="a",
    topic_id="my-topic-id",
    subscription_id="my-subscription-id",
    pubsub_topic_id="destination-topic-id",
    regional=True,
    target_location=BacklogLocation.BEGINNING,
):
    if regional:
        location = CloudRegion(cloud_region)
    else:
        location = CloudZone(CloudRegion(cloud_region), zone_id)

    topic_path = TopicPath(project_number, location, topic_id)
    subscription_path = SubscriptionPath(project_number, location, subscription_id)
    destination_topic_path = PublisherClient.topic_path(project_number, pubsub_topic_id)

    subscription = Subscription(
        name=str(subscription_path),
        topic=str(topic_path),
        delivery_config=Subscription.DeliveryConfig(
            # Possible values for delivery_requirement:
            # - `DELIVER_IMMEDIATELY`
            # - `DELIVER_AFTER_STORED`
            # You may choose whether to wait for a published message to be successfully written
            # to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
            # suitable for applications that need higher throughput.
            delivery_requirement=Subscription.DeliveryConfig.DeliveryRequirement.DELIVER_IMMEDIATELY,
        ),
        # Configures an export subscription that writes messages to a Pub/Sub topic.
        export_config=ExportConfig(
            # Possible values for desired_state:
            # - `ACTIVE`: enable message processing.
            # - `PAUSED`: suspend message processing.
            desired_state=ExportConfig.State.ACTIVE,
            pubsub_config=ExportConfig.PubSubConfig(
                topic=destination_topic_path,
            ),
        ),
    )

    # Initialize client that will be used to send requests across threads. This
    # client only needs to be created once, and can be reused for multiple requests.
    client = AdminClient(cloud_region)
    try:
        response = client.create_subscription(subscription, target_location)
        print(f"{response.name} created successfully.")
    except AlreadyExists:
        print(f"{subscription_path} already exists.")

Aggiorna una sottoscrizione per l'esportazione

Puoi aggiornare gli abbonamenti Lite con la console Google Cloud, Google Cloud CLI o l'API Pub/Sub Lite. L'applicazione delle nuove impostazioni può richiedere fino a 30 secondi.

Console

  1. Vai alla pagina Abbonamenti Lite.

    Vai agli abbonamenti Lite

  2. Fai clic sull'ID sottoscrizione Lite.

  3. Nella pagina Dettagli dell'abbonamento Lite, fai clic su Modifica.

gCloud

Per aggiornare una sottoscrizione Lite, utilizza il comando gcloud pubsub lite-subscriptions update:

gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \
--location=LOCATION \
--delivery-requirement=DELIVERY_REQUIREMENT \
--export-pubsub-topic=PUBSUB_TOPIC_NAME \
--export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
--export-desired-state=DESIRED_STATE

Sostituisci quanto segue:

  • SUBSCRIPTION_ID: l'ID dell'abbonamento Lite
  • LOCATION: la località dell'abbonamento Lite.
  • DELIVERY_REQUIREMENT: facoltativo. Il requisito di consegna, deliver-after-stored o deliver-immediately.
  • PUBSUB_TOPIC_NAME: facoltativo. Il nome del Argomento Pub/Sub in cui eseguire l'esportazione. Specifica il nome completo se l'argomento si trova in un altro progetto: projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID: l'ID di un argomento Lite esistente da utilizzare come argomento non recapitabile. L'argomento deve essere nello stesso località (zona o regione) e progetto come abbonamento per l'esportazione.
  • DESIRED_STATE: facoltativo. Lo stato desiderato della sottoscrizione. Sono supportati i seguenti valori:
    • active: la sottoscrizione esporta i messaggi Lite in in Pub/Sub. (opzione predefinita).
    • paused: l'esportazione di messaggi Lite è sospesa.

Se la richiesta ha esito positivo, la riga di comando visualizza la sottoscrizione Lite:

Updated subscription [SUBSCRIPTION_ID].
deliveryConfig:
deliveryRequirement: DELIVERY_REQUIREMENT
exportConfig:
currentState: DESIRED_STATE
deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID
desiredState: DESIRED_STATE
pubsubConfig:
  topic: PUBSUB_TOPIC_NAME
name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID

Protocollo

Per aggiornare una sottoscrizione Lite, invia una richiesta PATCH come la seguente:

PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig
Authorization: Bearer $(gcloud auth print-access-token)

Sostituisci quanto segue:

  • REGION: la regione in cui è stata creata la sottoscrizione Lite.
  • PROJECT_NUMBER: il numero del progetto in cui Lite è stato creato un abbonamento.
  • LOCATION: la località in cui è stata creata la sottoscrizione Lite.
  • SUBSCRIPTION_ID: l'ID dell'abbonamento Lite.

Specifica i seguenti campi nel corpo della richiesta:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Sostituisci quanto segue:

  • DELIVERY_REQUIREMENT: il requisito di recapito, DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
  • DESIRED_STATE: lo stato desiderato per l'abbonamento. Sono supportati i seguenti valori:
    • ACTIVE: la sottoscrizione esporta i messaggi Lite in in Pub/Sub.
    • PAUSED: l'esportazione di messaggi Lite è sospesa.
  • DEAD_LETTER_TOPIC_ID: l'ID di un argomento Lite esistente da utilizzare come argomento messaggi non recapitabili. L'argomento deve trovarsi nella stessa località (zona o regione) e nello stesso progetto della sottoscrizione di esportazione stessa.
  • PUBSUB_TOPIC_NAME: il nome della destinazione Pub/Sub. Formato di esempio: projects/my-project-id/topics/my-topic-id.

Se la richiesta ha esito positivo, la risposta è la sottoscrizione Lite in JSON formato:

{
"deliveryConfig": {
  "deliveryRequirement": "DELIVERY_REQUIREMENT",
},
"exportConfig": {
  "desiredState": "DESIRED_STATE",
  "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
  "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }
},
"name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Mettere in pausa o avviare un abbonamento per l'esportazione

Le sottoscrizioni alle esportazioni hanno un'impostazione chiamata stato desiderato, che ha uno dei seguenti: due valori:

  • Attivo: la sottoscrizione esporta i messaggi Lite in Pub/Sub.
  • In pausa: l'esportazione dei messaggi Lite è sospesa.

Per modificare lo stato desiderato nella console Google Cloud:

  1. Vai alla pagina Abbonamenti Lite.

    Andare agli abbonamenti Lite

  2. Fai clic sull'ID sottoscrizione Lite.

  3. Nella pagina Dettagli abbonamento Lite, fai clic su Metti in pausa o Avvia.

Puoi anche aggiornare lo stato desiderato utilizzando Google Cloud CLI o l'API Pub/Sub Lite. Consulta: Aggiornare un abbonamento per l'esportazione.

Best practice

In questa sezione vengono descritte alcune best practice relative all'utilizzo dell'esportazione di abbonamenti.

Prenotazioni

Ti consigliamo di utilizzare un abbonamento per l'esportazione con una prenotazione anziché impostare esplicitamente la capacità di throughput dell'abbonamento.

Compatibilità dei messaggi

Se un messaggio Pub/Sub Lite non è compatibile con Pub/Sub, la sottoscrizione di esportazione non pubblica il messaggio in Pub/Sub. ma lo inserisce nell'argomento messaggi non recapitabili, se ne è stato assegnato uno. Se non è stato assegnato alcun argomento messaggi non recapitabili, i messaggi incompatibili vengono semplicemente ignorati.

Quando pubblichi messaggi nell'argomento Lite, tieni presente quanto segue problemi di compatibilità:

  • Chiavi. Le chiavi Pub/Sub Lite hanno il tipo bytes, mentre Le chiavi di ordinamento Pub/Sub sono di tipo string. Per garantire la compatibilità, La chiave Pub/Sub Lite deve contenere solo caratteri UTF-8.

  • Attributi. Gli attributi dei messaggi presentano i seguenti requisiti:

    • Per essere compatibili, tutti gli attributi dei messaggi Pub/Sub Lite devono avere un solo valore. Pub/Sub Lite supporta gli attributi del messaggio con più valori, ma Pub/Sub supporta solo gli attributi con un solo valore.
    • Gli attributi dei messaggi non devono superare Limiti dei messaggi Pub/Sub, inclusi il numero massimo di attributi per messaggio e la dimensione massima di chiave e valore per .

Argomento messaggi non recapitabili

Per conservare e gestire i messaggi incompatibili, ti consigliamo di utilizzare un argomento per i messaggi inutilizzati. Puoi assegnare un argomento per le email inutilizzate quando crei l'iscrizione all'esportazione oppure puoi aggiornare un'iscrizione all'esportazione esistente per utilizzare un argomento per le email inutilizzate. Se la sottoscrizione riceve un messaggio incompatibile con Pub/Sub, pubblica il messaggio nell'argomento messaggi non recapitabili.

Un argomento messaggi non recapitabili è un normale argomento Pub/Sub Lite. Deve trovarsi nella stessa posizione e nello stesso progetto della sottoscrizione di esportazione e deve essere un argomento diverso dall'argomento di origine.

In genere, un argomento messaggi non recapitabili ha un basso utilizzo della velocità effettiva. Pertanto, consigliamo di assegnare una prenotazione all'argomento messaggi non recapitabili anziché allocare il throughput all'argomento.

Errori di recapito

Una sottoscrizione di esportazione tenta di recapitare tutti i messaggi compatibili al relativo all'argomento Pub/Sub di destinazione. Se il recapito dei messaggi non riesce, l'iscrizione all'esportazione viene sospesa. Per trovare la categoria di errore, controlla la metrica subscription/export_status. I seguenti valori indicano un errore:

  • PERMISSION_DENIED: autorizzazioni insufficienti per esportare i messaggi.
  • NOT_FOUND: non sono state trovate una o più risorse; ad esempio, l'argomento destinazione non esiste.

Per ulteriori informazioni sulla risoluzione dei problemi, consulta Risolvere i problemi relativi alle sottoscrizioni di esportazione.

Una volta risolto l'errore, la sottoscrizione all'esportazione viene riavviata automaticamente a causa di nuovi tentativi periodici.

Prezzi

Ti vengono addebitati i costi delle risorse Pub/Sub Lite e Pub/Sub utilizzate dall'abbonamento all'esportazione. Nello specifico, ti verranno addebitati per la velocità effettiva dell'abbonamento allocato e lo spazio di archiviazione sottoscrizione Pub/Sub Lite, che è configurata per Pub/Sub Lite. Ti viene addebitata anche la pubblicazione nell' relativo all'argomento Pub/Sub di destinazione. Consulta: Prezzi di Pub/Sub.

Non sono previsti costi aggiuntivi per l'utilizzo della funzione di esportazione e non sono previsti differenza di prezzo tra le sottoscrizioni esportate in Pub/Sub Lite abbonamenti standard.

Risoluzione dei problemi di esportazione delle sottoscrizioni

Questa sezione descrive alcuni suggerimenti per la risoluzione dei problemi relativi all'esportazione degli abbonamenti.

La sottoscrizione all'esportazione è in pausa

Se l'abbonamento è in pausa, non viene esportato nessun messaggio.

Per rilevare questo problema:

  • Console Google Cloud: visualizza dettagli dell'abbonamento. Se l'abbonamento è in pausa, Stato desiderato e Stato attuale sono Paused.

  • Metriche: la metrica subscription/export_status è PAUSED.

Per risolvere il problema, avvia l'abbonamento.

L'argomento di destinazione o l'argomento della posta in arrivo è stato eliminato

Se elimini l'argomento Pub/Sub associato a un abbonamento all'esportazione o l'argomento messaggi non recapitabili, si verifica un errore.

Per rilevare questo problema:

  • Console Google Cloud: visualizza i dettagli dell'abbonamento. Se l'argomento è stato eliminato, lo stato attuale è Not found.

  • Metriche: la metrica subscription/export_status. Se l'argomento era eliminato, il valore è NOT_FOUND.

Per risolvere il problema, controlla l'argomento Pub/Sub di destinazione e l'argomento per le email inutilizzate (se è stato configurato).

Se Pub/Sub di destinazione è stato eliminato, ricrea l'argomento con lo stesso nome. La pubblicazione della sottoscrizione all'esportazione riprenderà, a condizione che le autorizzazioni non sono cambiate.

Se l'argomento messaggi non recapitabili è stato eliminato, creane uno nuovo e aggiorna per farvi riferimento.

Messaggi incompatibili

Se i messaggi non sono compatibili con Pub/Sub, non vengono esportati.

Per rilevare questo problema:

  • Metriche: la metrica subscription/unexportable_message_count mostra il numero di messaggi incompatibili che non è stato possibile esportare.

Per risolvere il problema, utilizza un argomento per i messaggi inutilizzati per conservare i messaggi incompatibili. Esamina i messaggi per determinare la causa, quindi trasformali e ripubblicali, se necessario. Consulta la sezione Compatibilità dei messaggi.

L'esportazione è limitata

Per rilevare questo problema:

  • Metriche: la metrica subscription/flow_control_status mostra un motivo di controllo del flusso NO_CLIENT_TOKENS, che indica che è stato raggiunto il limite per partizione di byte o messaggi in sospeso. Finché il problema non verrà risolto, la coda aumenterà per gli abbonamenti all'esportazione associati.

Questo errore ha diverse possibili cause principali. La maggior parte delle possibili cause si verifica sul back-end, ma controlla quanto segue:

  • Assicurati di pubblicare messaggi Lite che condividono la stessa chiave a una velocità inferiore a 1 MiB/s per chiave. La sottoscrizione di esportazione scrive le chiavi dei messaggi Lite come chiavi di ordinamento Pub/Sub e Pub/Sub ha un limite di 1 MiB/s per ogni chiave di ordinamento. Il superamento di questo limite può causare il throttling.

L'utente non è autorizzato a eseguire questa azione

L'agente di servizio Pub/Sub Lite deve disporre delle autorizzazioni per pubblicare nell'argomento Pub/Sub di destinazione.

Per rilevare questo problema:

  • Console Google Cloud: visualizza i dettagli dell'abbonamento. Se ci sono errori di autorizzazione, lo stato attuale è Permission denied.

  • Metriche: la metrica subscription/export_status è PERMISSON_DENIED.

Ad esempio, le seguenti situazioni possono causare questo errore:

  • L'agente di servizio Pub/Sub Lite non dispone dell'autorizzazione corretta o un ruolo per pubblicare messaggi nell'argomento Pub/Sub di destinazione per un altro progetto.
  • L'agente di servizio è stato rimosso dal criterio IAM del progetto principale dell'abbonamento all'esportazione.
  • La configurazione dell'agente di servizio Pub/Sub Lite è ancora in corso. Un servizio dell'agente viene creato automaticamente quando crei la prima sottoscrizione di esportazione in un progetto. L'errore di autorizzazione dovrebbe essere risolto automaticamente entro 10 minuti.

Per risolvere il problema, controlla se all'agente di servizio è stato concesso il ruolo o l'autorizzazione corretto. Vedi Agenti di servizio.

Passaggi successivi

Scegli tra Pub/Sub o Pub/Sub Lite.