Menyiapkan gRPC Cloud Endpoints untuk Cloud Run dengan ESPv2

Menyiapkan gRPC Cloud Endpoints untuk Cloud Run dengan ESPv2

OpenAPI   |  gRPC

Halaman ini menunjukkan cara menyiapkan Cloud Endpoints untuk Cloud Run dengan backend gRPC. Endpoints menggunakan Extensible Service Proxy V2 (ESPv2) sebagai gateway API. Untuk menyediakan pengelolaan API bagi Cloud Run, Anda men-deploy container ESPv2 yang telah dibuat sebelumnya ke Cloud Run. Kemudian, Anda membantu mengamankan layanan dengan menggunakan IAM Cloud Run sehingga ESPv2 dapat memanggilnya.

Dengan penyiapan ini, ESPv2 mencegat semua permintaan ke layanan Anda dan melakukan pemeriksaan yang diperlukan (seperti autentikasi) sebelum memanggil layanan. Saat layanan merespons, ESPv2 mengumpulkan dan melaporkan telemetri, seperti yang ditunjukkan pada gambar di bawah. Anda dapat melihat metrik untuk layanan di halaman Endpoints > Services di konsol Google Cloud .

Catatan: Pada grafik di atas, ESPv2 dan "backend" di-deploy di dua instance Cloud Run terpisah.

Untuk ringkasan Cloud Endpoints, lihat Tentang Endpoints dan Arsitektur Endpoints.

Bermigrasi ke ESPv2

Rilis Cloud Endpoints sebelumnya tidak mendukung gRPC di Cloud Run dengan ESP. Untuk menggunakan fitur ini, lakukan migrasi ke Extensible Service Proxy V2.

Daftar Tugas

Gunakan daftar tugas berikut saat Anda mengerjakan tutorial. Semua tugas diperlukan untuk menyelesaikan tutorial ini.

1. Buat Google Cloud project, dan jika Anda belum men-deploy Cloud Run Anda sendiri, deploy layanan gRPC backend contoh. Lihat Sebelum memulai.
2. Cadangkan nama host Cloud Run untuk layanan ESPv2. Lihat Mencadangkan nama host Cloud Run.
3. Buat dokumen konfigurasi gRPC API yang menjelaskan API Anda, dan konfigurasi rute ke Cloud Run. Lihat Mengonfigurasi Endpoint.
4. Deploy dokumen konfigurasi gRPC API untuk membuat layanan terkelola. Lihat Men-deploy konfigurasi Endpoints.
5. Buat image Docker ESPv2 baru dengan konfigurasi layanan Endpoints Anda. Lihat Membangun image ESPv2 baru.
6. Deploy container ESPv2 ke Cloud Run. Kemudian, berikan izin Identity and Access Management (IAM) kepada ESPv2 untuk memanggil layanan Anda. Lihat Men-deploy container ESPv2.
7. Panggil layanan. Lihat Mengirim permintaan ke API.
8. Melacak aktivitas ke layanan Anda. Lihat Melacak aktivitas API.
9. Hindari menimbulkan biaya pada akun Google Cloud Anda. Lihat Pembersihan.

Biaya

Di dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

• Cloud Run
• Endpoints

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Setelah menyelesaikan tugas yang dijelaskan dalam dokumen ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat. Untuk mengetahui informasi selengkapnya, baca bagian Pembersihan.

Sebelum memulai

Untuk menyiapkan:

1. Di konsol Google Cloud , buka halaman Manage resources dan buat project.

   Buka halaman Kelola resource

2. Pastikan penagihan diaktifkan untuk project Anda.

   Pelajari cara mengaktifkan penagihan

3. Catat project ID karena akan diperlukan nanti. Di bagian selanjutnya dari halaman ini, project ID ini disebut sebagai ESPv2_PROJECT_ID.

4. Catat nomor project karena akan diperlukan nanti. Di bagian lain halaman ini, nomor project ini disebut sebagai ESPv2_PROJECT_NUMBER.

5. Download dan instal Google Cloud CLI.

   Download gcloud CLI

6. Ikuti langkah-langkah di Panduan memulai gRPC Python untuk menginstal gRPC dan alat gRPC.

7. Deploy contoh backend python-grpc-bookstore-server layanan gRPC Cloud Run untuk digunakan dengan tutorial ini. Layanan gRPC menggunakan image container berikut:

   gcr.io/endpointsv2/python-grpc-bookstore-server:2

   Ikuti langkah-langkah di Panduan memulai: Men-deploy Container Contoh Bawaan untuk men-deploy layanan. Pastikan untuk mengganti image container yang ditentukan dalam panduan memulai cepat tersebut dengan gcr.io/endpointsv2/python-grpc-bookstore-server:2

   Catat region dan project ID tempat layanan Anda di-deploy. Di bagian selanjutnya dari halaman ini, project ID ini disebut sebagai BACKEND_PROJECT_ID. Nama layanan Cloud Run yang di-deploy disebut sebagai BACKEND_SERVICE_NAME. Nama host Cloud Run-nya disebut sebagai BACKEND_HOST_NAME.

Mencadangkan nama host Cloud Run

Anda harus mencadangkan nama host Cloud Run untuk layanan ESPv2 agar dapat mengonfigurasi dokumen OpenAPI atau konfigurasi layanan gRPC. Untuk mencadangkan nama host, Anda akan men-deploy container contoh ke Cloud Run. Selanjutnya, Anda akan men-deploy container ESPv2 ke layanan Cloud Run yang sama.

Catatan: Setiap layanan Cloud Run ESPv2 hanya dapat dikaitkan dengan satu dokumen OpenAPI atau konfigurasi layanan gRPC. Cadangkan nama host Cloud Run baru untuk setiap dokumen.

1. Pastikan gcloud CLI diizinkan untuk mengakses data dan layanan Anda.
   1. Log in.

      gcloud auth login

   2. Di tab browser baru yang terbuka, pilih akun yang memiliki peran Editor atau Pemilik di project yang Anda buat untuk men-deploy ESPv2 ke Cloud Run. Google Cloud
2. Tetapkan region.

   gcloud config set run/region us-central1

3. Deploy image contoh gcr.io/cloudrun/hello ke Cloud Run. Ganti ESPv2_CLOUD_RUN_SERVICE_NAME dengan nama yang ingin Anda gunakan untuk layanan.

   gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESPv2_PROJECT_ID
   

   Setelah berhasil diselesaikan, perintah akan menampilkan pesan yang mirip dengan berikut ini:

   Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

   Misalnya, jika Anda menyetel ESPv2_CLOUD_RUN_SERVICE_NAME ke gateway:

   Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

   Dalam contoh ini, https://gateway-12345-uc.a.run.app adalah CLOUD_RUN_SERVICE_URL dan gateway-12345-uc.a.run.app adalah ESPv2_CLOUD_RUN_HOSTNAME.

4. Catat ESPv2_CLOUD_RUN_SERVICE_NAME dan ESPv2_CLOUD_RUN_HOSTNAME. Selanjutnya, Anda akan men-deploy ESPv2 ke layanan Cloud Run ESPv2_CLOUD_RUN_SERVICE_NAME. Anda menentukan ESPv2_CLOUD_RUN_HOSTNAME di kolom host pada dokumen OpenAPI.

Mengonfigurasi Endpoint

Contoh bookstore-grpc berisi file yang perlu Anda salin secara lokal dan dikonfigurasi.

1. Buat file deskriptor protobuf mandiri dari file .proto layanan Anda:
   1. Simpan salinan bookstore.proto dari repositori contoh ke direktori kerja Anda saat ini. File ini menentukan API layanan Bookstore.
   2. Buat direktori berikut di direktori kerja Anda: mkdir generated_pb2
   3. Buat file deskriptor, api_descriptor.pb, menggunakan compiler buffer protokol protoc. Jalankan perintah berikut di direktori tempat Anda menyimpan bookstore.proto:

      python3 -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto

      Dalam perintah sebelumnya, --proto_path ditetapkan ke direktori kerja saat ini. Di lingkungan build gRPC, jika Anda menggunakan direktori yang berbeda untuk file input .proto, ubah --proto_path sehingga kompiler menelusuri direktori tempat Anda menyimpan bookstore.proto.

2. Buat file teks bernama api_config.yaml di direktori kerja saat ini (direktori yang sama dengan yang berisi bookstore.proto). Untuk memudahkan, halaman ini merujuk ke dokumen konfigurasi gRPC API dengan nama file tersebut, tetapi Anda dapat menamainya dengan nama lain jika mau. Tambahkan konten berikut ke file:

   # The configuration schema is defined by the service.proto file.
   # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
   
   type: google.api.Service
   config_version: 3
   name: CLOUD_RUN_HOSTNAME
   title: Cloud Endpoints + Cloud Run gRPC
   apis:
     - name: endpoints.examples.bookstore.Bookstore
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true
   backend:
     rules:
       - selector: "*"
         address: grpcs://BACKEND_HOST_NAME
   

   Indentasi penting untuk format yaml. Misalnya, kolom name harus berada di tingkat yang sama dengan type.

3. Di kolom name, tentukan CLOUD_RUN_HOSTNAME, bagian nama host dari URL yang dicadangkan di atas dalam Mencadangkan nama host Cloud Run. Jangan sertakan ID protokol, seperti https:// atau grpcs://.

4. Di kolom address di bagian backend.rules, ganti BACKEND_HOST_NAME dengan layanan Cloud Run gRPC Bookstore yang sebenarnya yang dibuat di Sebelum memulai.

   Catatan: Untuk menggunakan gRPC dengan TLS di Cloud Run, kolom address harus memiliki skema grpcs://, bukan https://.

5. Perhatikan nilai properti title dalam file api_config.yaml:

   title: Cloud Endpoints + Cloud Run gRPC

   Nilai properti title menjadi nama layanan Endpoints setelah Anda men-deploy konfigurasi.

6. Simpan dokumen konfigurasi gRPC API Anda.

Lihat Mengonfigurasi Endpoint untuk mengetahui informasi selengkapnya.

Mengonfigurasi persyaratan kunci API

Untuk mengontrol akses ke API, Anda dapat mengonfigurasi Cloud Endpoints agar memerlukan kunci API. Klien yang memanggil API Anda harus memberikan kunci API yang terkait dengan project Anda. Lihat Membatasi akses API dengan kunci API untuk mengetahui informasi selengkapnya.

Jika belum memiliki kunci API yang terkait dengan Google Cloud project yang Anda gunakan dalam panduan memulai ini, Anda dapat menambahkannya dengan mengikuti langkah-langkah di Membuat Kunci API.

Untuk menguji penerapan kunci API menggunakan kunci API yang terkait dengan Google Cloud project Anda, ikuti langkah-langkah berikut:

1. Aktifkan dukungan kunci API untuk layanan Anda. Masukkan perintah berikut, dengan:
   • CLOUD_RUN_HOSTNAME adalah komponen nama host dari URL yang ditetapkan untuk layanan ESPv2 di Cloud Run. Objek ini digunakan dalam kolom host dokumen OpenAPI untuk menentukan lokasi tempat API dihosting.

   gcloud services enable CLOUD_RUN_HOSTNAME

2. Buka file konfigurasi layanan gRPC project Anda.
3. Tambahkan bagian usage ke file.
4. Untuk menonaktifkan persyaratan kunci API untuk semua metode, tambahkan aturan allow_unregistered_calls dengan pemilih karakter pengganti ("*") dalam bagian usage.

   usage:
     rules:
     # Allow all methods to be called without an API key.
     - selector: "*"
       allow_unregistered_calls: true

5. Untuk menonaktifkan persyaratan kunci API untuk metode tertentu, tetapkan selector ke nama yang sepenuhnya memenuhi syarat dari metode tersebut, bukan karakter pengganti.

   usage:
     rules:
     # Allow the ListShelves method to be called without an API key.
     - selector: "endpoints.examples.bookstore.Bookstore.ListShelves"
       allow_unregistered_calls: true

6. Setelah memodifikasi file konfigurasi layanan, deploy konfigurasi yang telah diupdate ke layanan Endpoints Anda.

Memanggil API menggunakan kunci API

Memanggil API bervariasi, bergantung pada apakah Anda memanggil dari klien gRPC atau klien HTTP.

Klien gRPC

Jika metode memerlukan kunci API, klien gRPC harus meneruskan nilai kunci sebagai x-api-key metadata dengan panggilan metodenya.

Python

def run(
    host, port, api_key, auth_token, timeout, use_tls, servername_override, ca_path

Java

private static final class Interceptor implements ClientInterceptor {
  private final String apiKey;
  private final String authToken;

  private static Logger LOGGER = Logger.getLogger("InfoLogging");

  private static Metadata.Key<String> API_KEY_HEADER =
      Metadata.Key.of("x-api-key", Metadata.ASCII_STRING_MARSHALLER);
  private static Metadata.Key<String> AUTHORIZATION_HEADER =
      Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER);

  public Interceptor(String apiKey, String authToken) {
    this.apiKey = apiKey;
    this.authToken = authToken;
  }

  @Override
  public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
      MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, Channel next) {
    LOGGER.info("Intercepted " + method.getFullMethodName());
    ClientCall<ReqT, RespT> call = next.newCall(method, callOptions);

    call = new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(call) {
      @Override
      public void start(Listener<RespT> responseListener, Metadata headers) {
        if (apiKey != null && !apiKey.isEmpty()) {
          LOGGER.info("Attaching API Key: " + apiKey);
          headers.put(API_KEY_HEADER, apiKey);
        }
        if (authToken != null && !authToken.isEmpty()) {
          System.out.println("Attaching auth token");
          headers.put(AUTHORIZATION_HEADER, "Bearer " + authToken);
        }
        super.start(responseListener, headers);
      }
    };
    return call;
  }
}

Go

func main() {
	flag.Parse()

	// Set up a connection to the server.
	conn, err := grpc.Dial(*addr, grpc.WithInsecure())
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	defer conn.Close()
	c := pb.NewGreeterClient(conn)

	if *keyfile != "" {
		log.Printf("Authenticating using Google service account key in %s", *keyfile)
		keyBytes, err := ioutil.ReadFile(*keyfile)
		if err != nil {
			log.Fatalf("Unable to read service account key file %s: %v", *keyfile, err)
		}

		tokenSource, err := google.JWTAccessTokenSourceFromJSON(keyBytes, *audience)
		if err != nil {
			log.Fatalf("Error building JWT access token source: %v", err)
		}
		jwt, err := tokenSource.Token()
		if err != nil {
			log.Fatalf("Unable to generate JWT token: %v", err)
		}
		*token = jwt.AccessToken
		// NOTE: the generated JWT token has a 1h TTL.
		// Make sure to refresh the token before it expires by calling TokenSource.Token() for each outgoing requests.
		// Calls to this particular implementation of TokenSource.Token() are cheap.
	}

	ctx := context.Background()
	if *key != "" {
		log.Printf("Using API key: %s", *key)
		ctx = metadata.AppendToOutgoingContext(ctx, "x-api-key", *key)
	}
	if *token != "" {
		log.Printf("Using authentication token: %s", *token)
		ctx = metadata.AppendToOutgoingContext(ctx, "Authorization", fmt.Sprintf("Bearer %s", *token))
	}

	// Contact the server and print out its response.
	name := defaultName
	if len(flag.Args()) > 0 {
		name = flag.Arg(0)
	}
	r, err := c.SayHello(ctx, &pb.HelloRequest{Name: name})
	if err != nil {
		log.Fatalf("could not greet: %v", err)
	}
	log.Printf("Greeting: %s", r.Message)
}

Node.js

const makeGrpcRequest = (JWT_AUTH_TOKEN, API_KEY, HOST, GREETEE) => {
  // Uncomment these lines to set their values
  // const JWT_AUTH_TOKEN = 'YOUR_JWT_AUTH_TOKEN';
  // const API_KEY = 'YOUR_API_KEY';
  // const HOST = 'localhost:50051'; // The IP address of your endpoints host
  // const GREETEE = 'world';

  // Import required libraries
  const grpc = require('@grpc/grpc-js');
  const protoLoader = require('@grpc/proto-loader');
  const path = require('path');

  // Load protobuf spec for an example API
  const PROTO_PATH = path.join(__dirname, '/protos/helloworld.proto');

  const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
  });

  const protoObj = grpc.loadPackageDefinition(packageDefinition).helloworld;

  // Create a client for the protobuf spec
  const client = new protoObj.Greeter(HOST, grpc.credentials.createInsecure());

  // Build gRPC request
  const metadata = new grpc.Metadata();
  if (API_KEY) {
    metadata.add('x-api-key', API_KEY);
  } else if (JWT_AUTH_TOKEN) {
    metadata.add('authorization', `Bearer ${JWT_AUTH_TOKEN}`);
  }

  // Execute gRPC request
  client.sayHello({name: GREETEE}, metadata, (err, response) => {
    if (err) {
      console.error(err);
    }

    if (response) {
      console.log(response.message);
    }
  });
};

Klien HTTP

Jika Anda menggunakan fitur transkode HTTP Cloud Endpoints untuk gRPC, klien HTTP dapat mengirim kunci sebagai parameter kueri dengan cara yang sama seperti yang mereka lakukan untuk layanan OpenAPI.

Men-deploy konfigurasi Endpoint

Untuk men-deploy konfigurasi Endpoints, Anda menggunakan perintah gcloud endpoints services deploy. Perintah ini menggunakan Service Management untuk membuat layanan terkelola.

1. Pastikan Anda berada di direktori tempat file api_descriptor.pb dan api_config.yaml berada.
2. Pastikan project default yang saat ini digunakan oleh alat command line gcloud adalah project Google Cloud yang ingin Anda gunakan untuk men-deploy konfigurasi Endpoints. Validasi project ID yang ditampilkan dari perintah berikut untuk memastikan bahwa layanan tidak dibuat di project yang salah.

   gcloud config list project
   

   Jika Anda perlu mengubah project default, jalankan perintah berikut:

   gcloud config set project YOUR_PROJECT_ID
   

3. Deploy file proto descriptor dan file konfigurasi menggunakan Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   Saat membuat dan mengonfigurasi layanan, Service Management akan menampilkan informasi ke terminal. Setelah deployment selesai, pesan yang mirip dengan berikut akan ditampilkan:

   Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

   CONFIG_ID adalah ID konfigurasi layanan Endpoints unik yang dibuat oleh deployment. Contoh:

   Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
   

   Dalam contoh sebelumnya, 2017-02-13r0 adalah ID konfigurasi layanan dan bookstore.endpoints.example-project.cloud.goog adalah nama layanan. ID konfigurasi layanan terdiri dari stempel tanggal yang diikuti dengan nomor revisi. Jika Anda men-deploy konfigurasi Endpoints lagi pada hari yang sama, nomor revisi akan bertambah dalam ID konfigurasi layanan.

Memeriksa layanan yang diperlukan

Minimal, Endpoints dan ESP memerlukan layanan Google berikut diaktifkan:

Nama	Judul
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API

Dalam sebagian besar kasus, perintah gcloud endpoints services deploy mengaktifkan layanan yang diperlukan ini. Namun, perintah gcloud berhasil diselesaikan, tetapi tidak mengaktifkan layanan yang diperlukan dalam situasi berikut:

• Jika Anda menggunakan aplikasi pihak ketiga seperti Terraform, dan Anda tidak menyertakan layanan ini.

• Anda men-deploy konfigurasi Endpoints ke projectGoogle Cloud yang sudah ada dan layanan ini dinonaktifkan secara eksplisit di project tersebut.

Gunakan perintah berikut untuk mengonfirmasi bahwa layanan yang diperlukan sudah diaktifkan:

gcloud services list

Jika Anda tidak melihat layanan yang diperlukan tercantum, aktifkan layanan tersebut:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Aktifkan juga layanan Endpoints Anda:

gcloud services enable ENDPOINTS_SERVICE_NAME

Untuk menentukan ENDPOINTS_SERVICE_NAME, Anda dapat:

• Setelah men-deploy konfigurasi Endpoints, buka halaman Endpoints di Konsol Cloud. Daftar ENDPOINTS_SERVICE_NAME yang mungkin ditampilkan di kolom Nama layanan.

• Untuk OpenAPI, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan di kolom host spesifikasi OpenAPI. Untuk gRPC, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan di kolom name konfigurasi gRPC Endpoints.

Untuk mengetahui informasi selengkapnya tentang perintah gcloud, lihat layanan gcloud.

Jika Anda menerima pesan error, lihat Memecahkan masalah deployment konfigurasi Endpoints.

Lihat Men-deploy konfigurasi Endpoints untuk mengetahui informasi tambahan.

Membangun image ESPv2 baru

Buat konfigurasi layanan Endpoints menjadi image Docker ESPv2 baru. Anda akan men-deploy image ini ke layanan Cloud Run yang dicadangkan nanti.

Catatan:

Langkah ini wajib dilakukan.

Konfigurasi layanan harus dibangun ke dalam image Docker baru karena Cloud Run adalah layanan menskalakan ke nol. Artinya, jika tidak ada traffic, semua instance akan dihapus. Saat traffic meningkat, instance baru dibuat sesuai permintaan. Pembuatan instance layanan jenis ini juga disebut cold start. Lihat dokumentasi Konkurensi Cloud Run untuk mengetahui informasi selengkapnya.

Jika image Docker tidak memiliki konfigurasi layanan yang di-build di dalamnya, Cloud Run harus melakukan dua panggilan API ke Google ServiceManagement saat cold start. Panggilan ini dihitung dalam kuota Google ServiceManagement API Anda.

Dengan mem-build konfigurasi layanan ke dalam image Docker ESPv2, Anda menghapus dua panggilan API dan menghindari dampak pada jumlah kuota untuk layanan Google ServiceManagement. Langkah ini juga mempercepat pembuatan instance layanan baru dan mengurangi latensi untuk permintaan yang menunggu instance baru.

Anda harus menjalankan kembali seluruh langkah ini dan men-deploy ulang container baru:

• Setiap kali Anda mengubah dan men-deploy ulang konfigurasi layanan Endpoints. Jika tidak, perubahan pada konfigurasi layanan tidak akan diteruskan ke ESPv2.
• Saat versi baru ESPv2 dirilis. Jika tidak, ESPv2 versi lama akan tetap di-deploy.

Untuk membuat konfigurasi layanan menjadi image Docker ESPv2 baru:

1. Download skrip ini ke komputer lokal Anda tempat gcloud CLI diinstal.

   Catatan:

   Skrip ini memerlukan bash. Jika tidak menggunakan macOS/Linux, Anda dapat menjalankannya di Cloud Shell, Compute Engine, atau Windows Subsystem for Linux.

2. Jalankan skrip dengan perintah berikut:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESPv2_PROJECT_ID

   Catatan:

   Skrip ini dirancang untuk membuat folder dalam direktori /tmp. Pastikan Anda memiliki akses tulis untuk direktori /tmp saat menjalankan skrip ini.

   Jika akses tulis tidak tersedia untuk direktori /tmp, Anda harus mengubah skrip untuk menentukan direktori alternatif tempat Anda memiliki akses yang diperlukan untuk membuat folder.

   Untuk ESPv2_CLOUD_RUN_HOSTNAME, tentukan nama host URL yang Anda pesan di atas dalam Memesan nama host Cloud Run. Jangan sertakan ID protokol, https://.

   Contoh:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s gateway-12345-uc.a.run.app \
       -c 2019-02-01r0 -p your-project-id

3. Skrip menggunakan perintah gcloud untuk mendownload konfigurasi layanan, membuat konfigurasi layanan menjadi image ESPv2 baru, dan mengupload image baru ke registry container project Anda. Skrip otomatis menggunakan rilis ESPv2 terbaru, yang ditunjukkan oleh ESPv2_VERSION dalam nama gambar output. Gambar output diupload ke:

   gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID

   Contoh:

   gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

   Catatan:

   Teruskan tanda -z ke skrip untuk membuat gambar di lokasi registry yang berbeda.

   Misalnya, untuk mengirimkan image ESPv2 yang dihasilkan ke pusat data Uni Eropa, teruskan -z eu ke skrip.

Men-deploy container ESPv2

1. Deploy layanan Cloud Run ESPv2 dengan image baru yang Anda buat di atas. Ganti CLOUD_RUN_SERVICE_NAME dengan nama layanan Cloud Run yang sama dengan yang Anda gunakan saat pertama kali mencadangkan nama host di atas dalam Mencadangkan nama host Cloud Run:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESPv2_PROJECT_ID

   Catatan:

   Jika layanan gRPC Anda menggunakan protokol streaming apa pun, tambahkan flag --use-http2 ke perintah gcloud run deploy. Saat ini, tanda ini hanya didukung di gcloud beta run. Tambahkan tanda ini saat men-deploy ESPv2 dan layanan backend gRPC Cloud Run.

2. Jika ingin mengonfigurasi Endpoints untuk menggunakan opsi startup ESPv2 tambahan, seperti mengaktifkan CORS, Anda dapat meneruskan argumen dalam variabel lingkungan ESPv2_ARGS:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESPv2_PROJECT_ID

   Untuk mengetahui informasi dan contoh selengkapnya tentang cara menyetel variabel lingkungan ESPv2_ARGS, termasuk daftar opsi yang tersedia dan informasi tentang cara menentukan beberapa opsi, lihat Flag Extensible Service Proxy V2.

3. Beri ESPv2 izin untuk memanggil layanan Cloud Run Anda. Jalankan perintah berikut untuk setiap layanan. Dalam perintah berikut:
   Catatan:

   Langkah ini tidak diperlukan jika layanan ESPv2 Cloud Run di-deploy tanpa menggunakan tanda --service-account dan layanan backend BACKEND_SERVICE_NAME di-deploy di project ESPv2_PROJECT_NUMBER.

   • Ganti BACKEND_SERVICE_NAME dengan nama layanan Cloud Run yang dipanggil. Jika Anda menggunakan layanan yang dibuat dengan men-deploy `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, gunakan python-grpc-bookstore-server sebagai nilai ini.
   • Ganti ESPv2_PROJECT_NUMBER dengan nomor project yang Anda buat untuk ESPv2. Salah satu cara untuk menemukannya adalah dengan membuka halaman IAM di konsol Google Cloud dan menemukan Akun layanan komputasi default, yang merupakan akun layanan yang digunakan dalam flag `member`.

   gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
     --member "serviceAccount:[e-mail]" \
     --role "roles/run.invoker" \
     --platform managed \
     --project BACKEND_PROJECT_ID

Untuk mengetahui informasi selengkapnya, lihat Mengelola akses menggunakan IAM.

Mengirim permintaan ke API

Untuk mengirim permintaan ke contoh API, Anda dapat menggunakan contoh klien gRPC yang ditulis dalam Python.

1. Clone repositori git tempat kode klien gRPC dihosting:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. Ubah direktori kerja Anda:

   cd python-docs-samples/endpoints/bookstore-grpc/

3. Instal dependensi:

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

4. Kirim permintaan ke API contoh:

   python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true

   Tentukan nama host layanan ESPv2 Cloud Run Anda di CLOUD_RUN_HOSTNAME, tanpa ID protokol. Contoh:

   python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true

   • Lihat grafik aktivitas untuk API Anda di halaman Endpoints > Services.

     Buka halaman Endpoints Services

     Mungkin perlu waktu beberapa saat agar permintaan ditampilkan dalam grafik.

   • Lihat log permintaan untuk API Anda di halaman Logs Explorer.

     Buka halaman Logs Explorer

Jika Anda tidak mendapatkan respons yang berhasil, lihat Memecahkan masalah error respons.

Anda baru saja men-deploy dan menguji API di Endpoints.

Catatan: Jika Anda ingin memberi tahu kami apa yang Anda sukai tentang tutorial ini, silakan berikan masukan di bagian bawah halaman ini. Masukan Anda membantu kami meningkatkan kualitas tutorial ini.
Jika Anda mendapatkan error, bergabunglah ke grup Google google-cloud-endpoints dan beri tahu kami apa yang salah. Grup ini menerima respons dari pengguna Endpoints lainnya dan dari engineer Google, yang memantau grup.

Melacak aktivitas API

1. Lihat grafik aktivitas untuk API Anda di halaman Endpoints > Service di konsol Google Cloud .

   Melihat grafik aktivitas Endpoint

   Mungkin perlu waktu beberapa saat agar permintaan ditampilkan dalam grafik.

2. Lihat log permintaan untuk API Anda di halaman Logs Explorer.

   Melihat log permintaan Endpoints

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut.

Lihat Menghapus API dan instance API untuk mengetahui informasi tentang cara menghentikan layanan yang digunakan oleh tutorial ini.

Langkah berikutnya

• Pelajari Cloud Run lebih lanjut
• Pelajari lebih lanjut cara men-deploy konfigurasi Endpoints
• Membagikan API Anda kepada developer lain
• Mempelajari autentikasi
• Mentranskode HTTP/JSON ke gRPC
• Pelajari opsi dukungan komunitas