Compute Engine 用戶端程式庫

本頁說明如何開始使用 Compute Engine API 適用的 Cloud 用戶端程式庫。有了用戶端程式庫，您可以透過支援的語言，更輕鬆地存取Google Cloud API。雖然您可以直接向伺服器發出原始要求來使用Google Cloud API，但用戶端程式庫提供簡化功能，可大幅減少需要編寫的程式碼數量。

如要進一步瞭解 Cloud 用戶端程式庫和舊版 Google API 用戶端程式庫，請參閱「用戶端程式庫說明」。

如要直接在 Google Cloud 控制台中，按照這項工作的逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

安裝用戶端程式庫

C++

請按照 Quickstart操作。

C#

從 NuGet 安裝 Google.Cloud.Compute.V1 套件。

詳情請參閱「設定 C# 開發環境」。

Go

go get cloud.google.com/go/compute/apiv1

詳情請參閱「設定 Go 開發環境」。

Java

如果您使用 Maven，請將下列指令新增到 pom.xml 檔案中。如要進一步瞭解 BOM，請參閱 Google Cloud Platform 程式庫 BOM。

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

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-compute</artifactId>
  </dependency>
</dependencies>

如果您使用 Gradle，請將下列指令新增到依附元件中：

implementation 'com.google.cloud:google-cloud-compute:1.97.0'

如果您使用 sbt，請在依附元件中加入以下指令：

libraryDependencies += "com.google.cloud" % "google-cloud-compute" % "1.97.0"

舊版 Compute Engine 適用的 Java Cloud 用戶端程式庫可透過 Maven 構件取得，版本為 0.120.x 或更早。這個程式庫的 0.120.x 以下版本與後續版本不相容。

詳情請參閱「設定 Java 開發環境」。

Node.js

npm install @google-cloud/compute

舊版 Compute Engine 適用的 Node.js Cloud 用戶端程式庫，可在 npm 套件中以 2.5.x 以下版本提供。這個程式庫的 2.5.x 版和更早版本與後續版本不相容。

詳情請參閱「設定 Node.js 開發環境」。

PHP

composer require google/cloud-compute

詳情請參閱「在 Google Cloud 上使用 PHP」。

Python

pip install --upgrade google-cloud-compute

詳情請參閱「設定 Python 開發環境」。

Ruby

gem install google-cloud-compute-v1

詳情請參閱「設定 Ruby 開發環境」。

Rust

cargo add google-cloud-compute-v1

詳情請參閱「開始使用 Rust」。

設定驗證方法

為驗證向 Google Cloud API 發出的呼叫，用戶端程式庫支援應用程式預設憑證 (ADC)；程式庫會在定義的一組位置中尋找憑證，並使用這些憑證驗證向 API 發出的要求。有了 ADC，無需修改應用程式程式碼，就能在各種環境 (例如本機開發環境或正式環境)，為應用程式提供憑證。

在正式環境中，設定 ADC 的方式取決於服務和背景。詳情請參閱「設定應用程式預設憑證」。

在本機開發環境中，您可以使用與 Google 帳戶相關聯的憑證設定 ADC：

安裝 Google Cloud CLI。完成後，執行下列指令來初始化 Google Cloud CLI：
```
gcloud init
```
若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證：
```
gcloud auth application-default login
```
如果您使用 Cloud Shell，則不需要執行這項操作。

如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已使用聯合身分登入 gcloud CLI。

登入畫面會隨即顯示。登入後，您的憑證會儲存在 ADC 使用的本機憑證檔案中。

使用用戶端程式庫

以下範例說明如何使用用戶端程式庫，列出特定可用區中的執行個體。如需更多範例，請參閱「使用用戶端程式庫」。

C#


using Google.Cloud.Compute.V1;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class ListZoneInstancesAsyncSample
{
    public async Task<IList<Instance>> ListZoneInstancesAsync(
        // TODO(developer): Set your own default values for these parameters or pass different values when calling this method.
        string projectId = "your-project-id", 
        string zone = "us-central1-a")
    {
        // Initialize client that will be used to send requests. This client only needs to be created
        // once, and can be reused for multiple requests.
        InstancesClient client = await InstancesClient.CreateAsync();
        IList<Instance> allInstances = new List<Instance>();

        // Make the request to list all VM instances in the given zone in the specified project.
        await foreach(var instance in client.ListAsync(projectId, zone))
        {
            // The result is an Instance collection.
            Console.WriteLine($"Instance: {instance.Name}");
            allInstances.Add(instance);
        }

        return allInstances;
    }
}

Go

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/api/iterator"
)

// listInstances prints a list of instances created in given project in given zone.
func listInstances(w io.Writer, projectID, zone string) error {
	// projectID := "your_project_id"
	// zone := "europe-central2-b"
	ctx := context.Background()
	instancesClient, err := compute.NewInstancesRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewInstancesRESTClient: %w", err)
	}
	defer instancesClient.Close()

	req := &computepb.ListInstancesRequest{
		Project: projectID,
		Zone:    zone,
	}

	it := instancesClient.List(ctx, req)
	fmt.Fprintf(w, "Instances found in zone %s:\n", zone)
	for {
		instance, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "- %s %s\n", instance.GetName(), instance.GetMachineType())
	}
	return nil
}

Java


import com.google.cloud.compute.v1.Instance;
import com.google.cloud.compute.v1.InstancesClient;
import java.io.IOException;

public class ListInstance {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample
    String project = "your-project-id";
    String zone = "zone-name";
    listInstances(project, zone);
  }

  // List all instances in the given zone in the specified project ID.
  public static void listInstances(String project, String zone) 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. After completing all of your requests, call
    // the `instancesClient.close()` method on the client to 
    // safely clean up any remaining background resources.
    try (InstancesClient instancesClient = InstancesClient.create()) {
      // Set the project and zone to retrieve instances present in the zone.
      System.out.printf("Listing instances from %s in %s:", project, zone);
      for (Instance zoneInstance : instancesClient.list(project, zone).iterateAll()) {
        System.out.println(zoneInstance.getName());
      }
      System.out.println("####### Listing instances complete #######");
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment and replace these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const zone = 'europe-central2-b'

const compute = require('@google-cloud/compute');

// List all instances in the given zone in the specified project.
async function listInstances() {
  const instancesClient = new compute.InstancesClient();

  const [instanceList] = await instancesClient.list({
    project: projectId,
    zone,
  });

  console.log(`Instances found in zone ${zone}:`);

  for (const instance of instanceList) {
    console.log(` - ${instance.name} (${instance.machineType})`);
  }
}

listInstances();

PHP

use Google\Cloud\Compute\V1\Client\InstancesClient;
use Google\Cloud\Compute\V1\ListInstancesRequest;

/**
 * List all instances for a particular Cloud project and zone.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $zone Zone to list instances for (like "us-central1-a").
 *
 * @throws \Google\ApiCore\ApiException if the remote call fails.
 */
function list_instances(string $projectId, string $zone)
{
    // List Compute Engine instances using InstancesClient.
    $instancesClient = new InstancesClient();
    $request = (new ListInstancesRequest())
        ->setProject($projectId)
        ->setZone($zone);
    $instancesList = $instancesClient->list($request);

    printf('Instances for %s (%s)' . PHP_EOL, $projectId, $zone);
    foreach ($instancesList as $instance) {
        printf(' - %s' . PHP_EOL, $instance->getName());
    }
}

Python

from __future__ import annotations

from collections.abc import Iterable

from google.cloud import compute_v1


def list_instances(project_id: str, zone: str) -> Iterable[compute_v1.Instance]:
    """
    List all instances in the given zone in the specified project.

    Args:
        project_id: project ID or project number of the Cloud project you want to use.
        zone: name of the zone you want to use. For example: “us-west3-b”
    Returns:
        An iterable collection of Instance objects.
    """
    instance_client = compute_v1.InstancesClient()
    instance_list = instance_client.list(project=project_id, zone=zone)

    print(f"Instances found in zone {zone}:")
    for instance in instance_list:
        print(f" - {instance.name} ({instance.machine_type})")

    return instance_list

Ruby


require "google/cloud/compute/v1"

# Lists all instances in the given zone in the specified project.
#
# @param [String] project project ID or project number of the Cloud project you want to use.
# @param [String] zone name of the zone you want to use. For example: "us-west3-b"
# @return [Array<::Google::Cloud::Compute::V1::Instance>] Array of instances.
def list_instances project:, zone:
  # Initialize client that will be used to send requests. This client only needs to be created
  # once, and can be reused for multiple requests.
  client = ::Google::Cloud::Compute::V1::Instances::Rest::Client.new

  # Send the request to list all VM instances in the given zone in the specified project.
  instance_list = client.list project: project, zone: zone

  puts "Instances found in zone #{zone}:"
  instances = []
  instance_list.each do |instance|
    puts " - #{instance.name} (#{instance.machine_type})"
    instances << instance
  end
  instances
end

Rust

pub async fn quickstart(project_id: &str) -> anyhow::Result<()> {
    use google_cloud_compute_v1::client::Instances;
    use google_cloud_gax::paginator::ItemPaginator;

    const ZONE: &str = "us-central1-a";

    let client = Instances::builder().build().await?;
    println!("Listing instances for project {project_id}");
    let mut instances = client
        .list()
        .set_project(project_id)
        .set_zone(ZONE)
        .by_item();
    while let Some(item) = instances.next().await.transpose()? {
        println!("  {:?}", item.name);
    }
    println!("DONE");
    Ok(())
}

其他資源

C++

下方列出與 C++ 用戶端程式庫相關的其他資源連結：

C#

下方列出與 C++ 用戶端程式庫相關的其他資源連結：

Go

下方列出與 Go 用戶端程式庫相關的其他資源連結：

Java

下方列出與 Java 用戶端程式庫相關的其他資源連結：

Node.js

下方列出與 Node.js 用戶端程式庫相關的其他資源連結：

PHP

下方列出與 PHP 用戶端程式庫相關的其他資源連結：

Python

下方列出與 Python 用戶端程式庫相關的其他資源連結：

Ruby

下方列出與 Ruby 用戶端程式庫相關的其他資源連結：

Rust

下方列出與 Rust 用戶端程式庫相關的其他資源連結：

舊版用戶端程式庫

Cloud 用戶端程式庫採用我們最新的用戶端程式庫模型，且建議您使用這個選項，以程式輔助的方式存取 Cloud API。

如果無法使用 Cloud 用戶端程式庫，可以改用下列 Google API 用戶端程式庫：

語言	程式庫	資源
Go	Google API Go 用戶端程式庫	說明文件
Java	Google API Java 用戶端程式庫	說明文件
JavaScript	Google API JavaScript 用戶端程式庫	說明文件
.NET	Google API .NET 用戶端程式庫	說明文件
Node.js	Google API Node.js 用戶端程式庫	說明文件
Objective-C	Google API Objective-C 用戶端程式庫	說明文件
PHP	Google API PHP 用戶端程式庫	說明文件
Python	Google API Python 用戶端程式庫	說明文件
Ruby	Google API Ruby 用戶端程式庫	說明文件
Dart	Google API Dart 用戶端程式庫	說明文件

第三方 Compute Engine API 用戶端程式庫

libcloud

libcloud 是一個 Python 程式庫，可透過單一整合式 API 與多個雲端服務供應商互動。

自 2013 年 7 月起，Apache libcloud API 專案已開始支援 Compute Engine 並提供相關更新。支援多種 Compute Engine 功能，包括執行個體、磁碟、網路和負載平衡器。入門版試用程式提供程式碼範例，說明如何搭配使用 libcloud 和 Compute Engine。

jclouds

jclouds 是一個開放原始碼程式庫，可讓您透過多個 Cloud 供應商使用 Java 和 Clojure。

jclouds 雲端 API 支援 Compute Engine，可讓您管理虛擬機器、磁碟和網路等資源。自 1.9 版起，Compute Engine 已升級為 jclouds 核心。

fog.io

fog.io 是一個開放原始碼 Ruby 程式庫，可讓您透過單一 API 與多種雲端服務互動。

自 2013 年 5 月的 1.11.0 版起，fog.io cloud API 已開始支援 Compute Engine。支援建立和刪除等執行個體作業，以及磁碟、網路和負載平衡器等其他資源的管理作業。

Compute Engine 用戶端程式庫 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

安裝用戶端程式庫

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

設定驗證方法

使用用戶端程式庫

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

其他資源

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

舊版用戶端程式庫

第三方 Compute Engine API 用戶端程式庫

libcloud

jclouds

fog.io

Compute Engine 用戶端程式庫