Halaman ini diterjemahkan oleh Cloud Translation API.

Opsi startup Extensible Service Proxy

OpenAPI | gRPC

Extensible Service Proxy (ESP) adalah proxy berbasis NGINX yang memungkinkan Cloud Endpoints menyediakan fitur pengelolaan API. Anda mengonfigurasi ESP dengan menentukan opsi saat memulai penampung Docker ESP. Saat dimulai, penampung ESP akan menjalankan skrip yang disebut start_esp, yang menulis file konfigurasi NGINX menggunakan opsi yang Anda tentukan dan meluncurkan ESP.

Anda menentukan opsi startup ESP dalam perintah docker run, misalnya:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

Jika men-deploy ESP ke Kubernetes, Anda harus menentukan opsi startup dalam file manifes deployment di kolom args, misalnya:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

Tabel berikut menjelaskan opsi startup ESP.

Opsi singkat	Opsi panjang	Deskripsi
`-s SERVICE_NAME`	`--service SERVICE_NAME`	Menetapkan nama layanan Endpoint.
`-R ROLLOUT_STRATEGY`	`--rollout_strategy ROLLOUT_STRATEGY`	Tersedia di ESP versi 1.7.0 dan yang lebih baru. Tentukan `managed` atau `fixed`. Opsi `--rollout_strategy=managed` mengonfigurasi ESP untuk menggunakan konfigurasi layanan terbaru yang di-deploy. Saat Anda menentukan opsi ini, hingga 5 menit setelah Anda men-deploy konfigurasi layanan baru, ESP akan mendeteksi perubahan dan otomatis mulai menggunakannya. Sebaiknya tentukan opsi ini, bukan ID konfigurasi tertentu yang akan digunakan ESP. Anda tidak perlu menentukan opsi `--version` saat menetapkan `--rollout_strategy` ke `managed`.
`-v CONFIG_ID`	`--version CONFIG_ID`	Menetapkan ID konfigurasi layanan yang akan digunakan oleh ESP. Lihat Mendapatkan nama layanan dan ID konfigurasi untuk mengetahui informasi yang diperlukan guna menetapkan opsi ini. Saat menentukan `--rollout_strategy=fixed` atau saat tidak menyertakan opsi `--rollout_strategy`, Anda harus menyertakan opsi `--version` dan menentukan ID konfigurasi. Dalam hal ini, setiap kali men-deploy konfigurasi Endpoint baru, Anda harus memulai ulang ESP dengan ID konfigurasi baru.
`-p HTTP1_PORT`	`--http_port HTTP1_PORT`	Menetapkan port yang diekspos ESP untuk koneksi HTTP/1.x.¹
`-P HTTP2_PORT`	`--http2_port HTTP2_PORT`	Menetapkan port yang diekspos ESP untuk koneksi HTTP/2.¹
`-S SSL_PORT`	`--ssl_port SSL_PORT`	Menetapkan port yang diekspos ESP untuk koneksi HTTPS.¹
`-a BACKEND`	`--backend BACKEND`	Menetapkan alamat untuk server backend aplikasi HTTP/1.x. Nilai default untuk alamat backend adalah `http://127.0.0.1:8081`. Anda dapat menentukan awalan protokol, misalnya: `--backend=https://127.0.0.1:8000` Jika Anda tidak menentukan awalan protokol, default-nya adalah `http`. Jika server backend berjalan di Compute Engine dalam penampung, Anda dapat menentukan nama penampung dan port, misalnya: `--backend=my-api-container:8000` Untuk menentukan bahwa backend menerima traffic gRPC, tambahkan awalan `grpc://`. Misalnya; `--backend=grpc://127.0.0.1:8000` Jika server backend Anda berjalan di Compute Engine dalam penampung, dan menerima traffic gRPC, Anda dapat menentukan nama penampung dan port, misalnya: `--backend=grpc://my-api-container:8000`
`-N STATUS_PORT`	`--status_port STATUS_PORT`	Menetapkan port status (default: `8090`).
tidak ada	`--disable_cloud_trace_auto_sampling`	Secara default, ESP mengambil sampel 1 permintaan dari setiap 1.000 atau 1 permintaan dari setiap 10 detik yang diaktifkan dengan Cloud Trace. Tetapkan tanda ini untuk menonaktifkan pengambilan sampel otomatis tersebut. Cloud Trace masih dapat diaktifkan dari header HTTP permintaan dengan konteks rekaman aktivitas, terlepas dari nilai tanda ini. Lihat Melacak API untuk mengetahui informasi selengkapnya.
`-n NGINX_CONFIG`	`--nginx_config NGINX_CONFIG`	Menetapkan lokasi untuk file konfigurasi NGINX kustom. Jika Anda menentukan opsi ini, ESP akan mengambil file konfigurasi yang ditentukan, lalu segera meluncurkan NGINX dengan file konfigurasi kustom yang disediakan. Lihat Menggunakan konfigurasi nginx kustom untuk GKE untuk mengetahui informasi selengkapnya.
`-k SERVICE_ACCOUNT_KEY`	`--service_account_key SERVICE_ACCOUNT_KEY`	Menetapkan file JSON kredensial akun layanan. Jika disediakan, ESP akan menggunakan akun layanan untuk membuat token akses guna memanggil Service Infrastructure API. Satu-satunya saat Anda perlu menentukan opsi ini adalah saat ESP berjalan di platform selain Google Cloud, seperti desktop lokal, Kubernetes, atau penyedia cloud lainnya. Lihat Membuat akun layanan untuk mengetahui informasi selengkapnya.
`-z HEALTHZ_PATH`	`--healthz HEALTHZ_PATH`	Tentukan endpoint health check di port yang sama dengan backend aplikasi. Misalnya, `-z healthz` membuat ESP menampilkan kode `200` untuk lokasi `/healthz`, bukan meneruskan permintaan ke backend. Default: tidak digunakan.
tidak ada	`--dns DNS_RESOLVER`	Tentukan DNS resolver. Misalnya, `--dns 169.254.169.254` menggunakan server Metadata GCP sebagai DNS resolver. Jika tidak ditentukan, defaultnya adalah `8.8.8.8`.

¹ Port ini bersifat opsional dan harus berbeda satu sama lain. Jika Anda tidak menentukan opsi port apa pun, ESP akan menerima koneksi HTTP/1.x di port 8080. Untuk koneksi HTTPS, ESP mengharapkan secret TLS berada di /etc/nginx/ssl/nginx.crt dan /etc/nginx/ssl/nginx.key.

Contoh pemanggilan command line

Contoh berikut menunjukkan cara menggunakan beberapa argumen command line:

Untuk memulai ESP guna menangani permintaan yang masuk di port HTTP/1.x 80 dan port HTTPS 443, serta mengirim permintaan ke backend API Anda di 127.0.0.1:8000:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1
     --service=echo-api.endpoints.example-project-12345.cloud.goog \
        --rollout_strategy=managed \
        --http_port=80 \
        --ssl_port=443 \
        --backend=127.0.0.1:8000

Untuk memulai ESP dengan konfigurasi NGINX kustom menggunakan file kredensial akun layanan untuk mengambil konfigurasi layanan dan terhubung ke kontrol layanan:

sudo docker run \
    --detach \
    --volume=$HOME/Downloads:/esp \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=echo-api.endpoints.example-project-12345.cloud.goog \
    --rollout_strategy=managed \
    --service_account_key=/esp/serviceaccount.json \
    --nginx_config=/esp/nginx.conf

Perhatikan bahwa Anda harus menggunakan flag Docker --volume atau --mount untuk memasang file JSON yang berisi kunci pribadi untuk akun layanan dan file konfigurasi NGINX kustom sebagai volume di dalam penampung Docker ESP. Contoh sebelumnya memetakan direktori $HOME/Downloads di komputer lokal ke direktori esp dalam penampung. Saat Anda menyimpan file kunci pribadi untuk akun layanan, file tersebut biasanya didownload ke direktori Downloads. Anda dapat menyalin file kunci pribadi ke direktori lain jika mau. Lihat Mengelola data di Docker untuk mengetahui informasi selengkapnya.

Menambahkan dukungan CORS ke ESP

Silakan baca Mendukung CORS untuk mengetahui deskripsi opsi dukungan CORS yang tersedia. Bagian ini menjelaskan penggunaan flag startup ESP untuk mendukung CORS.

Untuk mengaktifkan dukungan CORS di ESP, sertakan opsi --cors_preset dan tetapkan ke basic atau cors_with_regex. Saat Anda menyertakan --cors_preset=basic atau --cors_preset=cors_with_regex, ESP:

Mengasumsikan semua jalur lokasi memiliki kebijakan CORS yang sama.
Merespons permintaan sederhana dan permintaan HTTP OPTIONS preflight.
Menyimpan hasil permintaan OPTIONS pra-penerbangan ke dalam cache hingga 20 hari (1728000 detik).

Menetapkan header respons ke nilai berikut:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
Access-Control-Expose-Headers: Content-Length,Content-Range

Untuk mengganti nilai default Access-Control-Allow-Origin, tentukan salah satu opsi berikut:

Opsi	Deskripsi
`--cors_allow_origin`	Gunakan dengan `--cors_preset=basic` untuk menetapkan `Access-Control-Allow-Origin` ke origin tertentu. Contoh: `--cors_preset=basic --cors_allow_origin=http://example.com`
`--cors_allow_origin_regex`	Gunakan dengan `--cors_preset=cors_with_regex`. Memungkinkan Anda menggunakan ekspresi reguler untuk menetapkan `Access-Control-Allow-Origin`. Contoh: `--cors_preset=cors_with_regex --cors_allow_origin_regex=^https?://.+\.example\.com$` Ekspresi reguler dalam contoh sebelumnya mengizinkan origin dengan `http` atau `https` dan subdomain apa pun dari `example.com`.

Setelah menetapkan --cors_preset=basic atau --cors_preset=cors_with_regex untuk mengaktifkan CORS, Anda dapat mengganti nilai default header respons lainnya dengan menentukan satu atau beberapa opsi berikut:

Opsi	Deskripsi
`--cors_allow_methods`	Menetapkan `Access-Control-Allow-Methods` ke metode HTTP yang ditentukan. Tentukan metode HTTP sebagai string dengan setiap metode HTTP dipisahkan oleh koma. Contoh: `--cors_preset=basic --cors_allow_methods=GET,POST,PUT,OPTIONS`
`--cors_allow_headers`	Menetapkan `Access-Control-Allow-Headers` ke header HTTP yang ditentukan. Tentukan header HTTP sebagai string dengan setiap header HTTP dipisahkan oleh koma. Contoh: `--cors_preset=basic --cors_allow_headers=Origin,Content-Type,Accept`
`--cors_allow_credentials`	Menyertakan header `Access-Control-Allow-Credentials` dengan nilai `true` dalam respons. Secara default, header `Access-Control-Allow-Credentials` tidak disertakan dalam respons. Contoh: `--cors_preset=basic --cors_allow_credentials`
`--cors_expose_headers`	Menetapkan `Access-Control-Expose-Headers` ke header yang ditentukan. Tentukan header yang dapat ditampilkan sebagai bagian dari respons sebagai string dengan setiap header dipisahkan oleh koma. Contoh: `--cors_preset=basic --cors_expose_headers=Content-Length`

Jika opsi startup CORS ESP tidak sesuai dengan kebutuhan aplikasi, Anda dapat membuat file nginx.conf kustom dengan dukungan CORS yang diperlukan aplikasi. Untuk mengetahui informasi selengkapnya, lihat Membuat nginx.conf kustom untuk mendukung CORS.

Langkah selanjutnya

Pelajari:

Men-deploy ESP dan backend API Anda ke Google Cloud
Menjalankan ESP secara lokal atau di platform lain
Skrip start_esp di GitHub