查看預約記錄或未來預留項目要求

本文說明如何查看預留項目、未來預留項目要求和預留項目用量。如要進一步瞭解預留項目，請參閱「選擇預留項目類型」。

查看預留項目、未來預留項目要求或預留項目用量時，您可以執行下列操作：

  • 查看預訂設定。這項檢閱作業可協助您驗證預留項目詳細資料、確保預留項目符合需求，以及規劃容量。

  • 判斷可消耗的執行個體數量。這項檢查可協助您判斷有多少 Compute Engine 執行個體可消耗預留容量。

  • 查看預訂項目用量。您可以透過這項檢查，確認特定 Compute Engine 執行個體耗用哪個預留項目，或列出專案中耗用特定預留項目的所有執行個體。

限制

您只能在建立共用預留項目或共用未來預留項目要求的專案中查看。

事前準備

  • 如果尚未設定驗證，請先完成設定。 驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，可以選取下列任一選項，向 Compute Engine 進行驗證：

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI： 

      gcloud init

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    2. Set a default region and zone.

    Go

    如要在本機開發環境中使用本頁面的 Go 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    詳情請參閱 Set up authentication for a local development environment。

    Java

    如要在本機開發環境中使用本頁面的 Java 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    詳情請參閱 Set up authentication for a local development environment。

    Node.js

    如要在本機開發環境中使用本頁面的 Node.js 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    詳情請參閱 Set up authentication for a local development environment。

    Python

    如要在本機開發環境中使用本頁面的 Python 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    詳情請參閱 Set up authentication for a local development environment。

    REST

    如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

必要的角色

如要取得查看預訂或未來預訂要求所需的權限，請要求管理員授予您專案的 Compute 管理員 (roles/compute.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備查看預留項目或未來預留項目要求所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要查看預留項目或未來預留項目要求，必須具備下列權限：

  • 如要查看保留項目清單： compute.reservations.list 專案
  • 如要查看未來預留項目要求清單： compute.futureReservations.list 專案
  • 如要查看預訂詳細資料： compute.reservations.get 專案的
  • 如要查看未來預留項目要求的詳細資料，請在專案上按一下 compute.futureReservations.get。

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

查看預訂設定

下列各節說明如何查看預訂或未來預訂要求的設定。

查看預留項目

如要查看一或多項預訂的設定，請使用本節所述的下列其中一種方法：

  • 如要查看專案中所有預訂項目的總覽，請查看預訂項目清單。

  • 如要查看單一預訂的完整詳細資料，請查看預訂詳細資料。

如要在預訂中查看 deleteAtTime 和 reservationSharingPolicy 欄位 (預覽版)，請使用 Google Cloud CLI 查看預訂詳細資料，或使用 REST API 查看預訂。如果不需要這些欄位，請選取下列任一選項，查看預訂記錄：

控制台

  1. 前往 Google Cloud 控制台的「Reservations」(預留項目) 頁面。

    前往「Reservations」(預留項目) 頁面

    在「On-demand reservations」(隨需預留項目) 分頁 (預設)，表格會列出每個預留項目，而每個表格欄位則說明一項屬性。

  2. 選用步驟：在「On-demand reservations」(隨需預留項目) 表格中，執行下列一或多項操作：

    • 如要顯示預訂的保證數量，請按一下「資料欄顯示選項...」，選取「保證數量」核取方塊，然後按一下「確定」。

    • 如要縮小預訂清單範圍，請在 「Filter」(篩選器) 欄位中，選取要用來篩選預訂項目的屬性。

  3. 如要查看預訂詳細資料，請按一下「名稱」欄中的預訂名稱。系統會開啟頁面，顯示預訂詳細資料。

gcloud

  • 如要查看預訂清單，請使用 gcloud compute reservations list 指令：

    gcloud compute reservations list

    輸出結果會與下列範例相似：

    NAME: r-01
IN_USE_COUNT: 0
COUNT: 5
ZONE: us-central1-a
SHARE_TYPE: LOCAL

NAME: r-02
IN_USE_COUNT: 3
COUNT: 10
ZONE: us-central1-f
SHARE_TYPE: LOCAL

    如要使用篩選運算式縮小預訂清單範圍，請加入 --filter 旗標：

    gcloud compute reservations list \
    --filter="FILTER_EXPRESSION"

    將 FILTER_EXPRESSION 改為篩選運算式。

  • 如要查看預訂詳細資料，請使用 gcloud compute reservations describe 指令：

    gcloud compute reservations describe RESERVATION_NAME \
    --zone=ZONE

    更改下列內容：

    • RESERVATION_NAME：現有預訂的名稱。

    • ZONE：預留項目所在的可用區。

    輸出結果會與下列範例相似：

    creationTimestamp: '2024-10-11T03:25:23.192-07:00'
id: '4488228526648280060'
kind: compute#reservation
name: r-01
selfLink: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/r-01
shareSettings:
  shareType: LOCAL
specificReservation:
  assuredCount: '50'
  count: '50'
  inUseCount: '25'
  instanceProperties:
    machineType: n2-standard-2
specificReservationRequired: false
status: READY
zone: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a

Go

  • 如要查看預訂清單，請使用下列程式碼範例：

    // Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package snippets

import (
	"context"
	"fmt"
	"io"

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

// Get list of reservations for given project in particular zone
func listReservations(w io.Writer, projectID, zone string) error {
	// projectID := "your_project_id"
	// zone := "us-west3-a"

	ctx := context.Background()
	reservationsClient, err := compute.NewReservationsRESTClient(ctx)
	if err != nil {
		return err
	}
	defer reservationsClient.Close()

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

	it := reservationsClient.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 %d\n", instance.GetName(), instance.GetSpecificReservation().GetCount())
	}

	return nil
}

  • 如要查看預訂詳細資料，請使用下列程式碼範例：

    // Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package snippets

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
)

// Get certain reservation for given project and zone
func getReservation(w io.Writer, projectID, zone, reservationName string) (*computepb.Reservation, error) {
	// projectID := "your_project_id"
	// zone := "us-west3-a"
	// reservationName := "your_reservation_name"

	ctx := context.Background()
	reservationsClient, err := compute.NewReservationsRESTClient(ctx)
	if err != nil {
		return nil, err
	}
	defer reservationsClient.Close()

	req := &computepb.GetReservationRequest{
		Project:     projectID,
		Reservation: reservationName,
		Zone:        zone,
	}

	reservation, err := reservationsClient.Get(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("unable to delete reservation: %w", err)
	}

	fmt.Fprintf(w, "Reservation: %s\n", reservation.GetName())

	return reservation, nil
}

Java

  • 如要查看預訂清單，請使用下列程式碼範例：

    /*
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package compute.reservation;

import com.google.cloud.compute.v1.Reservation;
import com.google.cloud.compute.v1.ReservationsClient;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class ListReservations {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String project = "YOUR_PROJECT_ID";
    // Zone in which reservations are located.
    String zone = "us-central1-a";

    listReservations(project, zone);
  }

  // List all reservations in the given project and zone.
  public static List<Reservation> listReservations(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.
    List<Reservation> listOfReservations = new ArrayList<>();

    try (ReservationsClient reservationsClient = ReservationsClient.create()) {
      for (Reservation reservation : reservationsClient.list(project, zone).iterateAll()) {
        listOfReservations.add(reservation);
        System.out.println("Reservation: " + reservation.getName());
      }
    }
    return listOfReservations;
  }
}

  • 如要查看預訂詳細資料，請使用下列程式碼範例：

    /*
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package compute.reservation;

import com.google.cloud.compute.v1.Reservation;
import com.google.cloud.compute.v1.ReservationsClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

public class GetReservation {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "YOUR_PROJECT_ID";
    // Name of the zone in which you want to create the reservation.
    String zone = "us-central1-a";
    // Name of the reservation you want to create.
    String reservationName = "test-reservation-name";

    getReservation(projectId, reservationName, zone);
  }

  // Retrieve a reservation with the given name in the given zone.
  public static Reservation getReservation(
      String projectId, String reservationName, 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.
    try (ReservationsClient reservationsClient = ReservationsClient.create()) {

      // Get the reservation.
      Reservation reservation = reservationsClient.get(projectId, zone, reservationName);

      System.out.println("Reservation: " + reservation.getName());
      return reservation;
    }
  }
}

Node.js

  • 如要查看預訂清單，請使用下列程式碼範例：

    /*
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

'use strict';

async function main() {
  // Import the Compute library
  const computeLib = require('@google-cloud/compute');

  // Instantiate a reservationsClient
  const reservationsClient = new computeLib.ReservationsClient();

  /**
   * TODO(developer): Update these variables before running the sample.
   */
  // The ID of the project where your reservations are located.
  const projectId = await reservationsClient.getProjectId();
  // The zone where your reservations are located.
  const zone = 'us-central1-a';

  async function callGetReservations() {
    const reservations = (
      await reservationsClient.list({
        project: projectId,
        zone,
      })
    )[0];

    console.log(JSON.stringify(reservations));
  }

  await callGetReservations();
}

main().catch(err => {
  console.error(err);
  process.exitCode = 1;
});

  • 如要查看預訂詳細資料，請使用下列程式碼範例：

    /*
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

'use strict';

async function main(reservationName) {
  // Import the Compute library
  const computeLib = require('@google-cloud/compute');

  // Instantiate a reservationsClient
  const reservationsClient = new computeLib.ReservationsClient();

  /**
   * TODO(developer): Update/uncomment these variables before running the sample.
   */
  // The ID of the project where your reservation is located.
  const projectId = await reservationsClient.getProjectId();
  // The zone where your reservation is located.
  const zone = 'us-central1-a';
  // The name of the reservation to return.
  // reservationName = 'reservation-01';

  async function callGetReservation() {
    const requestedReservation = (
      await reservationsClient.get({
        project: projectId,
        zone,
        reservation: reservationName,
      })
    )[0];

    console.log(JSON.stringify(requestedReservation));
  }

  await callGetReservation();
}

main(...process.argv.slice(2)).catch(err => {
  console.error(err);
  process.exitCode = 1;
});

Python

  • 如要查看預訂清單，請使用下列程式碼範例：

    # Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


# This file is automatically generated. Please do not modify it directly.
# Find the relevant recipe file in the samples/recipes or samples/ingredients
# directory and apply your changes there.


from google.cloud import compute_v1
from google.cloud.compute_v1.services.reservations.pagers import ListPager


def list_compute_reservation(project_id: str, zone: str = "us-central1-a") -> ListPager:
    """
    Lists all compute reservations in a specified Google Cloud project and zone.
    Args:
        project_id (str): The ID of the Google Cloud project.
        zone (str): The zone of the reservations.
    Returns:
        ListPager: A pager object containing the list of reservations.
    """

    client = compute_v1.ReservationsClient()

    reservations_list = client.list(
        project=project_id,
        zone=zone,
    )

    for reservation in reservations_list:
        print("Name: ", reservation.name)
        print(
            "Machine type: ",
            reservation.specific_reservation.instance_properties.machine_type,
        )
    # Example response:
    # Name:  my-reservation_1
    # Machine type:  n1-standard-1
    # Name:  my-reservation_2
    # Machine type:  n1-standard-1

    return reservations_list

  • 如要查看預訂詳細資料，請使用下列程式碼範例：

    # Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


# This file is automatically generated. Please do not modify it directly.
# Find the relevant recipe file in the samples/recipes or samples/ingredients
# directory and apply your changes there.


from google.cloud import compute_v1
from google.cloud.compute_v1.types import compute


def get_compute_reservation(
    project_id: str,
    zone: str = "us-central1-a",
    reservation_name="your-reservation-name",
) -> compute.Reservation:
    """
    Retrieves a compute reservation from GCP.
    Args:
        project_id (str): The ID of the Google Cloud project.
        zone (str): The zone of the reservation.
        reservation_name (str): The name of the reservation to retrieve.
    Returns:
        compute.Reservation: The reservation object retrieved from Google Cloud.
    """

    client = compute_v1.ReservationsClient()

    reservation = client.get(
        project=project_id,
        zone=zone,
        reservation=reservation_name,
    )

    print("Name: ", reservation.name)
    print("STATUS: ", reservation.status)
    print(reservation.specific_reservation)
    # Example response:
    # Name:  your-reservation-name
    # STATUS:  READY
    # count: 3
    # instance_properties {
    #   machine_type: "n1-standard-1"
    #   local_ssds {
    #     disk_size_gb: 375
    #     interface: "NVME"
    #   }
    # ...

    return reservation

REST

  • 如要查看預訂清單，請對 reservations.list 方法發出 GET 要求：

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

    更改下列內容：

    • PROJECT_ID：您建立預留事項的專案 ID。

    • ZONE：預留項目所在的可用區。

    輸出結果會與下列範例相似：

    {
  "kind": "compute#reservation",
  "id": "4100668622331754141",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-05",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
  "name": "reservation-05",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2"
    },
    "count": "100",
    "inUseCount": "0",
    "assuredCount": "100"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "shareSettings": {
    "shareType": "LOCAL"
  }
},
{
  "kind": "compute#reservation",
  "id": "2533514314332214789",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
  "name": "reservation-04",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2",
      "guestAccelerators": [
        {
          "acceleratorType": "nvidia-tesla-t4",
          "acceleratorCount": 1
        }
      ],
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    },
    "count": "50",
    "inUseCount": "25",
    "assuredCount": "50"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "shareSettings": {
    "shareType": "LOCAL"
  }
}

    如要使用篩選運算式縮小預訂清單範圍，請加入 filter 查詢參數：

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations?filter=FILTER_EXPRESSION

    將 FILTER_EXPRESSION 替換為使用網址編碼值的篩選運算式。

  • 如要查看預訂詳細資料，請對 reservations.get 方法發出 GET 要求。

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME

    更改下列內容：

    • PROJECT_ID：您建立預留資源的專案 ID。

    • ZONE：預留項目所在的可用區。

    • RESERVATION_NAME：現有預訂的名稱。

    輸出結果會與下列範例相似：

    {
  "kind": "compute#reservation",
  "id": "4488228526648280060",
  "creationTimestamp": "2024-10-11T03:25:23.192-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/davide-experimental/zones/us-central1-a/reservations/r-01",
  "zone": "https://www.googleapis.com/compute/v1/projects/davide-experimental/zones/us-central1-a",
  "name": "r-01",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n2-standard-2"
    },
    "count": "50",
    "inUseCount": "25",
    "assuredCount": "50"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "shareSettings": {
    "shareType": "LOCAL"
  }
}

查看未來預留項目要求

如要查看一或多個預訂要求的設定，請使用本節所述的下列其中一種方法：

  • 如要查看專案中所有未來預留項目要求的總覽，請查看要求清單。

  • 如要查看單一未來預留項目要求的完整詳細資料，請查看要求詳細資料。

如要查看未來的預留項目要求，請選取下列其中一個選項：

控制台

  1. 前往 Google Cloud 控制台的「Reservations」(預留項目) 頁面。

    前往「Reservations」(預留項目) 頁面

  2. 點選「Future reservations」(未來預留項目) 分頁標籤。

    表格會列出每項未來預留項目要求，而每個表格欄位則說明一項屬性。

  3. 選用步驟：如要縮小要求清單範圍，請在 「Filter」(篩選器) 欄位中，選取要用來篩選要求的屬性。

  4. 如要查看要求的詳細資料，請按一下「名稱」欄中的要求名稱。系統會開啟頁面，顯示未來預留要求詳細資料。

gcloud

  • 如要查看未來預留項目要求清單，請使用 gcloud compute future-reservations list 指令：

    gcloud compute future-reservations list

    輸出結果會與下列範例相似：

    NAME: fr-04
TOTAL_COUNT: 100
START_TIME: 2025-07-20T07:00:00Z
END_TIME: 2025-08-05T07:00:00Z
PROCUREMENT_STATUS: FULFILLED
ZONE: us-east1-a

NAME: fr-05
TOTAL_COUNT: 10
START_TIME: 2025-07-20T07:00:00Z
END_TIME: 2025-12-01T00:00:00Z
PROCUREMENT_STATUS: PENDING_APPROVAL
ZONE: us-west1-c

    如要使用篩選運算式縮小未來預留項目要求清單的範圍，請加入 --filter 標記：

    gcloud compute future-reservations list \
    --filter="FILTER_EXPRESSION"

    將 FILTER_EXPRESSION 改為篩選運算式。

  • 如要查看未來預留項目要求的詳細資料，請使用 gcloud compute future-reservations describe 指令：

    gcloud compute future-reservations describe FUTURE_RESERVATION_NAME \
    --zone=ZONE

    更改下列內容：

    • FUTURE_RESERVATION_NAME：現有未來預留項目要求的名稱。

    • ZONE：未來預留項目要求所在的可用區。

    輸出結果會與下列範例相似：

    autoCreatedReservationsDeleteTime: '2025-05-02T01:00:00Z'
creationTimestamp: '2025-03-23T10:08:31.613-07:00'
id: '5212276518668495076'
kind: compute#futureReservation
name: fr-01
planningStatus: SUBMITTED
selfLink: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/fr-01
selfLinkWithId: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/5212276518668495076
shareSettings:
  shareType: LOCAL
specificSkuProperties:
  instanceProperties:
    machineType: n1-standard-64
  totalCount: '800'
status:
  existingMatchingUsageInfo:
    count: '3'
    timestamp: '2025-03-30T01:00:00Z'
  lockTime: '2025-03-30T17:09:59.297799Z'
  procurementStatus: APPROVED
timeWindow:
  endTime: '2025-05-02T01:00:00Z'
  startTime: '2025-04-30T17:30:00Z'
zone: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a

REST

  • 如要查看未來預留項目要求清單，請向 futureReservations.list 方法發出 GET 要求：

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/futureReservations

    更改下列內容：

    • PROJECT_ID：您建立未來預留項目要求的專案 ID。

    • ZONE：未來預留項目要求所在的可用區。

    輸出結果會與下列範例相似：

    {
  "id": "projects/my-project/zones/us-east1-a/futureReservations",
  "items": [
    {
      "id": "743865190848184978",
      "creationTimestamp": "2025-03-23T18:16:45.274-07:00",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a/futureReservations/fr-base",
      "selfLinkWithId": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a/futureReservations/743865190848184978",
      "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a",
      "name": "fr-base",
      "specificSkuProperties": {
        "instanceProperties": {
          "machineType": "n1-standard-1"
        },
        "totalCount": "100"
      },
      "planningStatus": "SUBMITTED",
      "timeWindow": {
        "endTime": "2025-05-02T01:00:00Z",
        "startTime": "2025-04-30T17:30:00Z"
      },
      "status": {
        "procurementStatus": "FULFILLED",
        "lockTime": "2025-03-30T07:00:00Z",
        "existingMatchingUsageInfo": {
          "count": "3",
          "timestamp": "2025-03-30T01:00:00Z"
        }
      },
      "kind": "compute#futureReservation"
    },
    ...
  ],
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a/futureReservations",
  "etag": "AnzKY34l-cvvV-JnniESJ0dtQvQ=/hvc4jaHpxFAZmOt1FVtKNgzZu-M=",
  "kind": "compute#futureReservationsListResponse"
}

    如要使用篩選運算式篩選未來預留項目要求清單，請加入 filter 查詢參數：

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/aggregated/futureReservations?filter=FILTER_EXPRESSION

    將 FILTER_EXPRESSION 替換為使用網址編碼值的篩選運算式。

  • 如要查看未來預留項目要求的詳細資料，請對 futureReservations.get 方法發出 GET 要求：

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME

    更改下列內容：

    • PROJECT_ID：您建立未來預訂要求的專案 ID。

    • ZONE：未來預留項目要求所在的可用區。

    • FUTURE_RESERVATION_NAME：現有未來預留項目要求的名稱。

    輸出結果會與下列內容相似：

    {
  "autoCreatedReservationsDeleteTime": "2025-05-02T01:00:00Z",
  "creationTimestamp": "2025-03-23T10:08:31.613-07:00",
  "id": "5212276518668495076",
  "kind": "compute#futureReservation",
  "name": "fr-01",
  "planningStatus": "SUBMITTED",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/fr-01",
  "selfLinkWithId": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/5212276518668495076",
  "shareSettings": {
    "shareType": "LOCAL"
  },
  "specificSkuProperties": {
    "instanceProperties": {
      "machineType": "n1-standard-64"
    },
    "totalCount": "800"
  },
  "status": {
    "lockTime": "2025-03-30T17:09:59.297799Z",
    "procurementStatus": "APPROVED",
    "existingMatchingUsageInfo": {
      "count": "3",
      "timestamp": "2025-03-30T01:00:00Z"
    }
  },
  "timeWindow": {
    "endTime": "2025-05-02T01:00:00Z",
    "startTime": "2025-04-30T17:30:00Z"
  },
  "zone": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a"
}

判斷可使用的執行個體數量

如要判斷可使用預留容量的運算執行個體數量，請執行下列其中一項操作：

保留項目中可使用的執行個體

查看預訂詳細資料時，您可以查看下列欄位，瞭解有多少運算執行個體正在使用預訂項目，以及有多少執行個體可以使用預訂項目：

  • 保證數量 (assuredCount)：在預訂可用區內實際預訂的執行個體數量。這個數字包括專案保留的執行個體，以及與共用預留項目共用的任何專案。

  • 總數 (count)：預訂中指定的預留執行個體數量。這個數字應與保證數量相符。

  • 使用中的機器 (inUseCount)：專案中或共用預訂資源的專案中，正在消耗預訂資源的執行個體數量。

舉例來說，如果保證數量 (assuredCount) 和總數量 (count) 都是 50，而使用預留項目的執行個體數量 (inUseCount) 為 25，則在預留項目完全用完之前，還有 25 個執行個體可以使用。

未來預留項目要求中的可用執行個體

您可以決定 Compute Engine 在未來預留項目要求開始時間，要為多少個運算執行個體建立預留項目。如果是草稿、待核准或已核准的要求，您可以按照下列方式判斷這組號碼：

  1. 查看專案中以及要求共用的任何專案中，有多少執行中的執行個體和未使用的預訂項目符合要求屬性。

  2. 從要求中的總數減去相符的執行中執行個體和未使用的預留項目數量。

您可以一次判斷單一或多個要求可耗用的執行個體數量。如要發出多個要求，請使用 Google Cloud 控制台或 REST API。如要提出單一要求，請選取下列任一選項：

控制台

  1. 前往 Google Cloud 控制台的「Reservations」(預留項目) 頁面。

    前往「Reservations」(預留項目) 頁面

  2. 點選「Future reservations」(未來預留項目) 分頁標籤。

    表格會列出每項未來預留項目要求，而每個表格欄位則說明一項屬性。

  3. 如要判斷 Compute Engine 計畫在要求開始時間預留的執行個體數量，請從「總計數量」欄減去「相符數量」欄。

    「相符數量」欄會顯示下列其中一個警告：

    • 相符數量為零：專案中沒有相符的執行中執行個體或未使用的預訂，或要求共用的任何專案中也沒有。

    • 相符數量等於總數量：Compute Engine 不會在開始時間為您的要求預留任何執行個體。

    如果您修改要求，或是建立符合要求的新執行個體或預訂，Compute Engine 會在 30 分鐘內更新「相符數量」欄。

  4. 選用：如要查看要求中「相符數量」欄的上次更新時間，請按照下列步驟操作：

    1. 在「Name」(名稱) 欄中，按一下要求的名稱。系統會開啟頁面，顯示未來預留要求詳細資料。

    2. 在「資源詳細資料」部分，查看「上次評估相符用量的時間」欄位。

gcloud

  1. 如要查看未來預留項目要求的詳細資料，請使用 gcloud compute future-reservations describe 指令：

    gcloud compute future-reservations describe FUTURE_RESERVATION_NAME \
    --zone=ZONE

    更改下列內容：

    • FUTURE_RESERVATION_NAME：現有未來預留項目要求的名稱。

    • ZONE：未來預留項目要求所在的可用區。

    在輸出內容中，找出 count 和 totalCount 欄位：

    ...
specificSkuProperties:
  ...
  totalCount: '100'
status:
  existingMatchingUsageInfo:
    count: '50'
    timestamp: '2025-03-30T01:00:00Z'
  ...
  procurementStatus: DRAFTING
...

  2. 從 totalCount 減去 count 的值。舉例來說，如果 count 為 50，而 totalCount 為 100，則 Compute Engine 會在要求啟動時間自動為 50 個執行個體建立預留資源。

    如果您修改要求，或是建立符合要求的新執行個體或預訂，Compute Engine 會在 30 分鐘內更新 existingMatchingUsageInfo 欄位。如要確認這個欄位上次更新的時間，請檢查 existingMatchingUsageInfo.timestamp 的值。

REST

  1. 如要查看未來預留項目要求清單，請對 futureReservations.list 方法發出 GET 要求。在要求網址中加入 filter 查詢參數，並指定只顯示 name、specificSkuProperties 和 status 欄位：

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/futureReservations?fields=items.name,items.specificSkuProperties,items.status

    更改下列內容：

    • PROJECT_ID：您建立未來預留項目要求的專案 ID。

    • ZONE：未來預留項目要求所在的可用區。

    在輸出內容中，找出每個草稿、待核准或已核准要求的 count 和 totalCount 欄位：

    {
  "items": [
    {
      "specificSkuProperties": {
        ...
        totalCount: "100"
      },
      "name": "fr-01",
      "status": {
        "procurementStatus": "APPROVED",
        ...
        existingMatchingUsageInfo: {
          count: "50",
          "timestamp": "2025-01-22T07:54:26.295Z"
        }
      }
    },
    {
      "specificSkuProperties": {
        ...
        totalCount: "20"
      },
      "name": "fr-02",
      "status": {
        "procurementStatus": "DRAFTING",
        ...
        existingMatchingUsageInfo: {
          "count": "2",
          "timestamp": "2025-01-22T07:54:26.295Z"
        }
      }
    }
  ]
}

  2. 針對每項要求，從 totalCount 中減去 count 的值。舉例來說，如果 count 為 50，totalCount 為 100，則 Compute Engine 會在要求啟動時間自動建立 50 個執行個體的預留項目。

    如果您修改要求，或是建立符合要求的新執行個體或預訂，Compute Engine 會在 30 分鐘內更新 existingMatchingUsageInfo 欄位。如要確認這個欄位上次更新的時間，請檢查 existingMatchingUsageInfo.timestamp 的值。

日曆模式中未來預留要求的可使用執行個體

查看未來預留項目要求的詳細資料時，您可以瞭解 Compute Engine 預計在要求開始時間佈建的運算執行個體數量。無論專案或任何與要求共用的專案中，有多少個相符的執行個體，Compute Engine 都會建立要求中指定的執行個體數量。

查看預留項目使用情形

每當運算執行個體使用預留資源時，您都可以查看下列資訊：

查看執行個體使用的預留項目

如要查看執行個體使用的預訂項目，請選取下列其中一個選項：

控制台

  1. 前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面。

    前往 VM 執行個體

  2. 按一下要查看的執行個體名稱，該執行個體會耗用預訂項目。

  3. 在「基本資訊」部分，「已使用的預訂項目」欄位會顯示執行個體使用的預訂項目名稱。

gcloud

如要查看執行個體使用的預留項目，請使用 gcloud compute instances describe 指令並加上 --flatten=resourceStatus.reservationConsumptionInfo 旗標：

gcloud compute instances describe INSTANCE_NAME \
    --flatten=resourceStatus.reservationConsumptionInfo \
    --zone=ZONE

更改下列內容：

  • INSTANCE_NAME：執行個體的名稱。
  • ZONE：執行個體所在的區域。

您會看到類似以下的輸出內容：

consumedReservation: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation

REST

如要查看執行個體使用的保留項目，請對 instances.get 方法發出 GET 要求。在要求網址中，加入設為 resourceStatus.reservationConsumptionInfo 的 fields 查詢參數：

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/var>/zones/ZONE/instances/INSTANCE_NAME?fields=resourceStatus.reservationConsumptionInfo

更改下列內容：

  • PROJECT_ID：執行個體所在的專案 ID。
  • ZONE：執行個體所在的區域。
  • INSTANCE_NAME：執行個體的名稱。

你會看到類似以下的回應：

{
  "resourceStatus": {
    "reservationConsumptionInfo": {
      "consumedReservation": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations/example-reservation"
    }
  }
}

查看使用保留項目的執行個體清單

您可以查看單一專案中，使用預留資源的執行個體清單。如果是共用預留項目，這個方法只會傳回您指定的專案中的執行個體，不會納入使用相同預留項目的其他消費者專案中的執行個體。

如要查看使用預留項目的執行個體，請選取下列其中一個選項：

gcloud

如要查看使用保留項目的執行個體，請使用 gcloud compute instances list 指令，並將 --filter 標記設為要查看的保留項目：

gcloud compute instances list \
    --project=CONSUMER_PROJECT_ID \
    --zones=ZONE \
    --filter="resourceStatus.reservationConsumptionInfo.consumedReservation:https://www.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME"

更改下列內容：

  • CONSUMER_PROJECT_ID：使用預留項目的專案 ID。
  • ZONE：預留項目和執行個體所在的可用區。
  • HOST_PROJECT_ID：建立預訂的專案 ID (如與消費者專案不同)。
  • RESERVATION_NAME：預訂名稱。

您會看到類似以下的輸出內容：

NAME               ZONE           MACHINE_TYPE  PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP     STATUS
my-e2-instance     us-central1-c  e2-medium                  10.128.0.61  35.239.208.172  RUNNING
my-e2-instance-02  us-central1-c  e2-medium                  10.128.0.62  104.154.31.123  RUNNING
my-e2-instance-03  us-central1-c  e2-medium                  10.128.0.63  34.171.90.254   RUNNING

REST

如要查看使用保留項目的執行個體，請對 instances.list 方法發出 GET 要求。在要求網址中，加入設為要查看預訂名稱的 filter 查詢參數：

GET https://compute.googleapis.com/compute/v1/projects/CONSUMER_PROJECT_ID/zones/ZONE/instances?filter=resourceStatus.reservationConsumptionInfo.consumedReservation%3D%22.*%2Fprojects%2FHOST_PROJECT_ID%2Fzones%2FZONE%2Freservations%2FRESERVATION_NAME%22

更改下列內容：

  • CONSUMER_PROJECT_ID：使用預留項目的專案 ID。
  • ZONE：預留項目和執行個體所在的可用區。
  • HOST_PROJECT_ID：建立預訂的專案 ID (如與消費者專案不同)。
  • RESERVATION_NAME：預訂名稱。

你會看到類似以下的回應：

{
  "kind": "compute#instanceList",
  "id": "projects/example-project/zones/us-central1-a/instances",
  "items": [
    {
      ...
      "name": "example-instance-01",
      ...
      "resourceStatus": {
        "scheduling": {},
        "reservationConsumptionInfo": {
          "consumedReservation": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations/example-reservation"
        }
      }
    },
    {
      ...
      "name": "example-instance-02",
      ...
      "resourceStatus": {
        "scheduling": {},
        "reservationConsumptionInfo": {
          "consumedReservation": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations/example-reservation"
        }
      },
      ...
    }
  ],
  "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances"
}

後續步驟