The Storage Control API provides a unified place for performing
metadata-oriented control plane operations, which include network routing,
resource management, and long-running operations. The Storage Control API is
separate from the Cloud Storage API, which handles data plane operations
that move your data within Google Cloud.

The following instructions describe how to get started with the Storage Control
API by using Cloud Storage client libraries.

## Install the client library

### C++

For more information about installing the C++ library, see
[Setting up a C++ development environment](https://docs.cloud.google.com/cpp/docs/setup.md.txt).

### C#

If you are using Visual Studio 2017 or higher, open nuget package manager window and type the following:

```
Install-Package Google.Cloud.Storage.Control.V2
```

If you are using .NET Core command-line interface tools to install your dependencies, run the following command:

```
dotnet add package Google.Cloud.Storage.Control.V2
```

For more information, see [Setting up a C# Development Environment](https://docs.cloud.google.com/dotnet/docs/setup.md.txt).

### Go

```go
go get cloud.google.com/go/storage/control/apiv2
```

For more information, see [Setting up a Go Development Environment](https://docs.cloud.google.com/go/docs/setup.md.txt).

### Java

```java
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.37.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage</artifactId>
  </dependency>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage-control</artifactId>
  </dependency>
```

For more information, see [Setting up a Java Development Environment](https://docs.cloud.google.com/java/docs/setup.md.txt).

### Node.js

```javascript
npm install @google-cloud/storage-control
```

For more information, see [Setting up a Node.js Development Environment](https://docs.cloud.google.com/nodejs/docs/setup.md.txt).

### PHP

```
composer require google/cloud-storage-control
```

For more information, see [Setting up a PHP Development Environment](https://docs.cloud.google.com/php/docs.md.txt).

### Python

```python
pip install google-cloud-storage-control
```

For more information, see [Setting up a Python Development Environment](https://docs.cloud.google.com/python/docs/setup.md.txt).

### Ruby

```ruby
gem install google-cloud-storage-control
```

For more information, see [Setting up a Ruby Development Environment](https://docs.cloud.google.com/ruby/docs/setup.md.txt).

## Set up authentication

Use the [Cloud Storage authentication instructions](https://docs.cloud.google.com/storage/docs/reference/libraries.md.txt#authentication) for setting up client
libraries.

## Use Storage Control

### C++


For more information, see the
[Cloud Storage C++ API
reference documentation](https://cloud.google.com/cpp/docs/reference/storagecontrol/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```c++
#include "google/cloud/storagecontrol/v2/storage_control_client.h"
#include <iostream>

int main(int argc, char* argv[]) try {
  if (argc != 2) {
    std::cerr << "Usage: " << argv[0] << " bucket-id\n";
    return 1;
  }
  auto const name =
      std::string{"projects/_/buckets/"} + argv[1] + "/storageLayout";

  namespace storagecontrol = ::google::cloud::storagecontrol_v2;
  auto client = storagecontrol::StorageControlClient(
      storagecontrol::MakeStorageControlConnection());

  auto layout = client.GetStorageLayout(name);
  if (!layout) throw std::move(layout).status();
  std::cout << layout->DebugString() << "\n";

  return 0;
} catch (google::cloud::Status const& status) {
  std::cerr << "google::cloud::Status thrown: " << status << "\n";
  return 1;
}
```

### C#


For more information, see the
[Cloud Storage C# API
reference documentation](https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Storage.Control.V2/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```c#
using Google.Cloud.Storage.Control.V2;
using System;

public class StorageControlQuickstartSample
{
    public StorageLayout StorageControlQuickstart(string bucketName = "your-unique-bucket-name")
    {
        StorageControlClient storageControl = StorageControlClient.Create();

        // Using "_" for projectId means global bucket namespace
        var layoutName = new StorageLayoutName("_", bucketName);
        StorageLayout response = storageControl.GetStorageLayout(layoutName);

        Console.WriteLine($"Bucket {bucketName} has location type {response.LocationType}");
        return response;
    }
}
```

### Go


For more information, see the
[Cloud Storage Go API
reference documentation](https://cloud.google.com/go/docs/reference/cloud.google.com/go/storage/latest/control/apiv2/controlpb).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```go
// This sample demonstrates how to set up and make an API call with the
// Storage Control client.
package main

import (
	"context"
	"flag"
	"fmt"
	"log"
	"time"

	control "cloud.google.com/go/storage/control/apiv2"
	controlpb "cloud.google.com/go/storage/control/apiv2/controlpb"
)

func main() {
	// Set this flag to an existing Cloud Storage bucket when running the sample.
	bucketName := flag.String("bucket", "", "Cloud Storage bucket name")
	flag.Parse()
	log.Printf("bucket : %v", *bucketName)

	ctx := context.Background()

	// Create a client.
	client, err := control.NewStorageControlClient(ctx)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	defer client.Close()

	// Create a request to get the storage layout for the bucket.
	req := &controlpb.GetStorageLayoutRequest{
		Name: fmt.Sprintf("projects/_/buckets/%v/storageLayout", *bucketName),
	}

	// Set a context timeout and send the request.
	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
	defer cancel()

	res, err := client.GetStorageLayout(ctx, req)
	if err != nil {
		log.Fatalf("GetStorageLayout: %v", err)
	}

	// Use response.
	fmt.Printf("Bucket %v has location type %v", bucketName, res.LocationType)
}
```

### Java


For more information, see the
[Cloud Storage Java API
reference documentation](https://cloud.google.com/java/docs/reference/google-cloud-storage/latest/com.google.storage.control.v2).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```java
import com.google.storage.control.v2.GetStorageLayoutRequest;
import com.google.storage.control.v2.StorageControlClient;
import com.google.storage.control.v2.StorageLayout;
import com.google.storage.control.v2.StorageLayoutName;

public class QuickstartStorageControlSample {
  public static void main(String... args) throws Exception {
    String bucketName = args[0]; // "your-bucket-name";

    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
      GetStorageLayoutRequest request =
          GetStorageLayoutRequest.newBuilder()
              // Set project to "_" to signify global bucket
              .setName(StorageLayoutName.format("_", bucketName))
              .build();
      StorageLayout response = storageControlClient.getStorageLayout(request);
      System.out.printf("Performed getStorageLayout request for %s%n", response.getName());
    }
  }
}
```

### Node.js


For more information, see the
[Cloud Storage Node.js API
reference documentation](https://cloud.google.com/nodejs/docs/reference/storage-control/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```javascript
/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Name of the bucket for which to get the layout
 */
// const bucketName = 'abc123'

// Imports the Control library
const {StorageControlClient} = require('@google-cloud/storage-control').v2;

// Instantiates a client
const controlClient = new StorageControlClient();

async function callGetStorageLayout() {
  // Construct request
  const request = {
    name: `projects/_/buckets/${bucketName}/storageLayout`,
  };

  // Run request
  const [layout] = await controlClient.getStorageLayout(request);

  // Use response
  console.log(
    `Bucket ${bucketName} has location type ${layout.locationType}.`
  );
}

callGetStorageLayout();
```

### PHP


For more information, see the
[Cloud Storage PHP API
reference documentation](https://cloud.google.com/php/docs/reference/cloud-storage-control/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```php
// Includes the autoloader for libraries installed with composer
require __DIR__ . '/../vendor/autoload.php';

// Imports the Google Cloud client library
use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
use Google\Cloud\Storage\Control\V2\GetStorageLayoutRequest;

// Instantiates a client
$storageControlClient = new StorageControlClient();

// The name for the new bucket
$bucketName = 'my-new-bucket';

// Set project to "_" to signify global bucket
$formattedName = $storageControlClient->storageLayoutName('_', $bucketName);
$request = (new GetStorageLayoutRequest())->setName($formattedName);

$response = $storageControlClient->getStorageLayout($request);

echo 'Performed get_storage_layout request for ' . $response->getName() . PHP_EOL;
```

### Python


For more information, see the
[Cloud Storage Python API
reference documentation](https://cloud.google.com/python/docs/reference/google-cloud-storage-control/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```python
from google.cloud import storage_control_v2


def storage_control_quickstart(bucket_name: str) -> None:
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    storage_control_client = storage_control_v2.StorageControlClient()
    # The storage layout path uses the global access pattern, in which
    # the "_" denotes this bucket exists in the global namespace.
    layout_path = storstorage_control_v2rStorageControlClientrage_layout_path(
        project="_", bucket=bucket_name
    )
    request = storstorage_control_v2SGetStorageLayoutRequest      name=layout_path,
    )
    response = storstorage_control_client.get_storage_layoutuest=request)

    print(f"Performed get_storage_layout request for {response.name}")
```

### Ruby


For more information, see the
[Cloud Storage Ruby API
reference documentation](https://cloud.google.com/ruby/docs/reference/google-cloud-storage-control/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```ruby
def quickstart bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage/control"

  storage_control = Google::Cloud::Storage::Control.storage_control

  # The storage layout path uses the global access pattern, in which the "_"
  # denotes this bucket exists in the global namespace.
  layout_path = storage_control.storage_layout_path project: "_", bucket: bucket_name

  request = Google::Cloud::Storage::Control::V2::GetStorageLayoutRequest.new name: layout_path

  response = storage_control.get_storage_layout request

  puts "Performed get_storage_layout request for #{response.name}"
end
```

### Rust

```rust
use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let layout = client
        .get_storage_layout()
        .set_name(format!("projects/_/buckets/{bucket_id}/storageLayout"))
        .send()
        .await?;
    println!("successfully retrieved storage layout: {layout:?}");
    Ok(())
}
```

## What's next

- Learn more about [Storage Control API](https://docs.cloud.google.com/storage/docs/reference/rpc.md.txt) capabilities.