Create and manage pools

This page shows you how to create and manage Live Stream API pools. A pool is a processing unit allocated for each Google Cloud project per region and is shared between all channels in a given region. Pools are used to protect input endpoints within a VPC Service Controls perimeter. For more information, see Use VPC Service Controls to secure your pipeline.

Set up your Google Cloud project and authentication

If you have not created a Google Cloud project and credentials, see Before you begin.

Create a pool

When you create an input endpoint in a location for the first time, the default pool for that location is automatically created.

Get pool details

To get the details of the pool, use the projects.locations.pools.get method.

REST

Before using any of the request data, make the following replacements:

• PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
• LOCATION: use one of the supported regions in which you have already created an input
  Show locations
  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • us-west2
  • northamerica-northeast1
  • southamerica-east1
  • asia-east1
  • asia-east2
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/pools/default"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/pools/default" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/pools/default",
  "createTime": CREATE_TIME,
  "updateTime": UPDATE_TIME
}

C#

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API C# API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.Video.LiveStream.V1;

public class GetPoolSample
{
    public Pool GetPool(
         string projectId, string locationId, string poolId)
    {
        // Create the client.
        LivestreamServiceClient client = LivestreamServiceClient.Create();

        GetPoolRequest request = new GetPoolRequest
        {
            PoolName = PoolName.FromProjectLocationPool(projectId, locationId, poolId)
        };

        // Make the request.
        Pool response = client.GetPool(request);
        return response;
    }
}

Go

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Go API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import (
	"context"
	"fmt"
	"io"

	livestream "cloud.google.com/go/video/livestream/apiv1"
	"cloud.google.com/go/video/livestream/apiv1/livestreampb"
)

// getPool gets a pool.
func getPool(w io.Writer, projectID, location, poolID string) error {
	// projectID := "my-project-id"
	// location := "us-central1"
	// poolID := "default"
	ctx := context.Background()
	client, err := livestream.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	req := &livestreampb.GetPoolRequest{
		Name: fmt.Sprintf("projects/%s/locations/%s/pools/%s", projectID, location, poolID),
	}

	response, err := client.GetPool(ctx, req)
	if err != nil {
		return fmt.Errorf("GetPool: %w", err)
	}

	fmt.Fprintf(w, "Pool: %v", response.Name)
	return nil
}

Java

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Java API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.video.livestream.v1.LivestreamServiceClient;
import com.google.cloud.video.livestream.v1.Pool;
import com.google.cloud.video.livestream.v1.PoolName;
import java.io.IOException;

public class GetPool {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String location = "us-central1";
    String poolId = "default"; // only 1 pool supported per location

    getPool(projectId, location, poolId);
  }

  public static void getPool(String projectId, String location, String poolId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. In this example, try-with-resources is used
    // which automatically calls close() on the client to clean up resources.
    try (LivestreamServiceClient livestreamServiceClient = LivestreamServiceClient.create()) {
      PoolName name = PoolName.of(projectId, location, poolId);
      Pool response = livestreamServiceClient.getPool(name);
      System.out.println("Pool: " + response.getName());
    }
  }
}

Node.js

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Node.js API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// projectId = 'my-project-id';
// location = 'us-central1';
// poolId = 'my-pool';

// Imports the Livestream library
const {LivestreamServiceClient} = require('@google-cloud/livestream').v1;

// Instantiates a client
const livestreamServiceClient = new LivestreamServiceClient();

async function getPool() {
  // Construct request
  const request = {
    name: livestreamServiceClient.poolPath(projectId, location, poolId),
  };
  const [pool] = await livestreamServiceClient.getPool(request);
  console.log(`Pool: ${pool.name}`);
}

getPool();

PHP

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API PHP API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\Cloud\Video\LiveStream\V1\Client\LivestreamServiceClient;
use Google\Cloud\Video\LiveStream\V1\GetPoolRequest;

/**
 * Gets a pool.
 *
 * @param string  $callingProjectId   The project ID to run the API call under
 * @param string  $location           The location of the pool
 * @param string  $poolId             The ID of the pool
 */
function get_pool(
    string $callingProjectId,
    string $location,
    string $poolId
): void {
    // Instantiate a client.
    $livestreamClient = new LivestreamServiceClient();
    $formattedName = $livestreamClient->poolName($callingProjectId, $location, $poolId);

    // Get the pool.
    $request = (new GetPoolRequest())
        ->setName($formattedName);
    $response = $livestreamClient->getPool($request);
    // Print results
    printf('Pool: %s' . PHP_EOL, $response->getName());
}

Python

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Python API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import argparse

from google.cloud.video import live_stream_v1
from google.cloud.video.live_stream_v1.services.livestream_service import (
    LivestreamServiceClient,
)


def get_pool(project_id: str, location: str, pool_id: str) -> live_stream_v1.types.Pool:
    """Gets a pool.
    Args:
        project_id: The GCP project ID.
        location: The location of the pool.
        pool_id: The user-defined pool ID."""

    client = LivestreamServiceClient()

    name = f"projects/{project_id}/locations/{location}/pools/{pool_id}"
    response = client.get_pool(name=name)
    print(f"Pool: {response.name}")

    return response

Ruby

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Ruby API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/video/live_stream"

##
# Get the pool
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param location [String] The location (e.g. "us-central1")
# @param pool_id [String] Your pool name (e.g. "default")
#
def get_pool project_id:, location:, pool_id:
  # Create a Live Stream client.
  client = Google::Cloud::Video::LiveStream.livestream_service

  # Build the resource name of the pool.
  name = client.pool_path project: project_id, location: location, pool: pool_id

  # Get the pool.
  pool = client.get_pool name: name

  # Print the pool name.
  puts "Pool: #{pool.name}"
end

Update a pool

To update an input endpoint, use the projects.locations.pools.patch method.

REST

Before using any of the request data, make the following replacements:

• PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
• LOCATION: the location of the default pool; use one of the supported regions
  Show locations
  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • us-west2
  • northamerica-northeast1
  • southamerica-east1
  • asia-east1
  • asia-east2
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
• NETWORK: the user-defined identifier for the network in the current project to peer with the service

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "networkConfig": {
    "peeredNetwork": "projects/PROJECT_NUMBER/global/networks/NETWORK"
  }
}
EOF

Then execute the following command to send your REST request:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/pools/default?updateMask=networkConfig"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "networkConfig": {
    "peeredNetwork": "projects/PROJECT_NUMBER/global/networks/NETWORK"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/pools/default?updateMask=networkConfig" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_NUMBER/locations/LOCATION/pools/default",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

This command creates a long-running operation (LRO) that you can use to track the progress of your request. See Manage long-running operations for more information.

C#

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API C# API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.Video.LiveStream.V1;
using Google.LongRunning;
using Google.Protobuf.WellKnownTypes;
using System.Threading.Tasks;

public class UpdatePoolSample
{
    public async Task UpdatePoolAsync(
         string projectId, string locationId, string poolId, string peeredNetwork)
    {
        // Create the client.
        LivestreamServiceClient client = LivestreamServiceClient.Create();

        UpdatePoolRequest request = new UpdatePoolRequest
        {
            Pool = new Pool
            {
                PoolName = PoolName.FromProjectLocationPool(projectId, locationId, poolId),
                NetworkConfig = new Pool.Types.NetworkConfig
                {
                    PeeredNetwork = peeredNetwork
                }
            },
            UpdateMask = new FieldMask { Paths = { "network_config" } }
        };

        // Make the request.
        Operation<Pool, OperationMetadata> response = await client.UpdatePoolAsync(request);
        // Get the name of the operation.
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name.
        Operation<Pool, OperationMetadata> retrievedResponse = await client.PollOnceUpdatePoolAsync(operationName);
        // Check if the retrieved long-running operation has completed.
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result.
            _ = retrievedResponse.Result;
        }
    }
}

Go

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Go API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import (
	"context"
	"fmt"
	"io"

	livestream "cloud.google.com/go/video/livestream/apiv1"
	"cloud.google.com/go/video/livestream/apiv1/livestreampb"
	"google.golang.org/protobuf/types/known/fieldmaskpb"
)

// updatePool updates the pool's peered network.
func updatePool(w io.Writer, projectID, location, poolID, peeredNetwork string) error {
	// projectID := "my-project-id"
	// location := "us-central1"
	// poolID := "default"
	// peeredNetwork :=  "projects/my-network-project-number/global/networks/my-network-name"
	ctx := context.Background()
	client, err := livestream.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	req := &livestreampb.UpdatePoolRequest{
		Pool: &livestreampb.Pool{
			Name: fmt.Sprintf("projects/%s/locations/%s/pools/%s", projectID, location, poolID),
			NetworkConfig: &livestreampb.Pool_NetworkConfig{
				PeeredNetwork: peeredNetwork,
			},
		},
		UpdateMask: &fieldmaskpb.FieldMask{
			Paths: []string{
				"network_config",
			},
		},
	}
	// Updates the pool.
	op, err := client.UpdatePool(ctx, req)
	if err != nil {
		return fmt.Errorf("UpdatePool: %w", err)
	}
	response, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %w", err)
	}

	fmt.Fprintf(w, "Updated pool: %v", response.Name)
	return nil
}

Java

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Java API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.video.livestream.v1.LivestreamServiceClient;
import com.google.cloud.video.livestream.v1.Pool;
import com.google.cloud.video.livestream.v1.Pool.NetworkConfig;
import com.google.cloud.video.livestream.v1.PoolName;
import com.google.cloud.video.livestream.v1.UpdatePoolRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UpdatePool {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String location = "us-central1";
    String poolId = "default";
    String peeredNetwork = "";

    updatePool(projectId, location, poolId, peeredNetwork);
  }

  public static void updatePool(String projectId, String location, String poolId,
      String peeredNetwork)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // 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.
    LivestreamServiceClient livestreamServiceClient = LivestreamServiceClient.create();
    var updatePoolRequest =
        UpdatePoolRequest.newBuilder()
            .setPool(
                Pool.newBuilder()
                    .setName(PoolName.of(projectId, location, poolId).toString())
                    .setNetworkConfig(
                        NetworkConfig.newBuilder()
                            .setPeeredNetwork(peeredNetwork)
                            .build()

                    ))
            .setUpdateMask(FieldMask.newBuilder().addPaths("network_config").build())
            .build();
    // Update pool can take 20+ minutes.
    Pool result =
        livestreamServiceClient.updatePoolAsync(updatePoolRequest).get(20, TimeUnit.MINUTES);
    System.out.println("Updated pool: " + result.getName());
    livestreamServiceClient.close();
  }
}

Node.js

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Node.js API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// projectId = 'my-project-id';
// location = 'us-central1';
// poolId = 'my-pool';
// peeredNetwork = 'projects/my-network-project-number/global/networks/my-network-name';

// Imports the Livestream library
const {LivestreamServiceClient} = require('@google-cloud/livestream').v1;

// Instantiates a client
const livestreamServiceClient = new LivestreamServiceClient();

async function updatePool() {
  // Construct request
  const request = {
    pool: {
      name: livestreamServiceClient.poolPath(projectId, location, poolId),
      networkConfig: {
        peeredNetwork: peeredNetwork,
      },
    },
    updateMask: {
      paths: ['network_config'],
    },
  };

  // Run request
  const [operation] = await livestreamServiceClient.updatePool(request);
  const response = await operation.promise();
  const [pool] = response;
  console.log(`Updated pool: ${pool.name}`);
}

updatePool();

PHP

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API PHP API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\Cloud\Video\LiveStream\V1\Pool;
use Google\Cloud\Video\LiveStream\V1\Client\LivestreamServiceClient;
use Google\Cloud\Video\LiveStream\V1\UpdatePoolRequest;
use Google\Protobuf\FieldMask;

/**
 * Updates a pool.
 *
 * @param string  $callingProjectId   The project ID to run the API call under
 * @param string  $location           The location of the pool
 * @param string  $poolId             The ID of the pool to be updated
 * @param string  $peeredNetwork      The updated peer network
 */
function update_pool(
    string $callingProjectId,
    string $location,
    string $poolId,
    string $peeredNetwork
): void {
    // Instantiate a client.
    $livestreamClient = new LivestreamServiceClient();

    $formattedName = $livestreamClient->poolName($callingProjectId, $location, $poolId);
    $pool = (new Pool())
        ->setName($formattedName)
        ->setNetworkConfig(
            (new Pool\NetworkConfig())
                ->setPeeredNetwork($peeredNetwork));

    $updateMask = new FieldMask([
        'paths' => ['network_config']
    ]);

    // Run the pool update request. The response is a long-running operation ID.
    $request = (new UpdatePoolRequest())
        ->setPool($pool)
        ->setUpdateMask($updateMask);
    $operationResponse = $livestreamClient->updatePool($request);

    $operationResponse->pollUntilComplete();
    if ($operationResponse->operationSucceeded()) {
        $result = $operationResponse->getResult();
        // Print results
        printf('Updated pool: %s' . PHP_EOL, $result->getName());
    } else {
        $error = $operationResponse->getError();
        // handleError($error)
    }
}

Python

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Python API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import argparse

from google.cloud.video import live_stream_v1
from google.cloud.video.live_stream_v1.services.livestream_service import (
    LivestreamServiceClient,
)
from google.protobuf import field_mask_pb2 as field_mask


def update_pool(
    project_id: str, location: str, pool_id: str, peered_network: str
) -> live_stream_v1.types.Pool:
    """Updates an pool.
    Args:
        project_id: The GCP project ID.
        location: The location of the pool.
        pool_id: The user-defined pool ID.
        peered_network: The updated peer network (e.g.,
        'projects/my-network-project-number/global/networks/my-network-name')."""

    client = LivestreamServiceClient()

    name = f"projects/{project_id}/locations/{location}/pools/{pool_id}"

    pool = live_stream_v1.types.Pool(
        name=name,
        network_config=live_stream_v1.types.Pool.NetworkConfig(
            peered_network=peered_network,
        ),
    )
    update_mask = field_mask.FieldMask(paths=["network_config"])

    operation = client.update_pool(pool=pool, update_mask=update_mask)
    response = operation.result()
    print(f"Updated pool: {response.name}")

    return response

Ruby

To learn how to install and use the client library for Live Stream API, see Live Stream API client libraries. For more information, see the Live Stream API Ruby API reference documentation.

To authenticate to Live Stream API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/video/live_stream"

##
# Update the pool's peered network
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param location [String] The location (e.g. "us-central1")
# @param pool_id [String] Your pool name (e.g. "my-pool")
# @param peered_network [String] The updated peer network
#   (e.g. "projects/my-network-project-number/global/networks/my-network-name")
#
def update_pool project_id:, location:, pool_id:, peered_network:
  # Create a Live Stream client.
  client = Google::Cloud::Video::LiveStream.livestream_service

  # Build the resource name of the pool.
  name = client.pool_path project: project_id, location: location, pool: pool_id

  # Set the update mask.
  update_mask = { paths: ["network_config"] }

  # Update the pool's peered network.
  update_pool = {
    name: name,
    network_config: {
      peered_network: peered_network
    }
  }

  operation = client.update_pool update_mask: update_mask, pool: update_pool

  # The returned object is of type Gapic::Operation. You can use this
  # object to check the status of an operation, cancel it, or wait
  # for results. Here is how to block until completion:
  operation.wait_until_done!

  # Print the pool name.
  puts "Updated pool: #{operation.response.name}"
end