Mulai menggunakan Pemroses Ekstensi Apigee

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara mengonfigurasi Pemroses Ekstensi Apigee untuk mengaktifkan penerapan kebijakan API untuk traffic API menggunakan load balancer yang mendukung Ekstensi Layanan.

Untuk mempelajari lebih lanjut kasus penggunaan yang disarankan dan manfaat menggunakan Pemroses Ekstensi Apigee untuk pengelolaan API, lihat Ringkasan Pemroses Ekstensi Apigee.

Prosesor Ekstensi Apigee adalah ekstensi traffic (jenis Ekstensi Layanan) yang memungkinkan Anda menggunakan Cloud Load Balancing untuk mengirimkan panggilan dari jalur pemrosesan data load balancer aplikasi ke Prosesor Ekstensi Apigee. Setelah load balancer dan ekstensi traffic dikonfigurasi, traffic API akan diproses oleh load balancer. Kebijakan di Pemroses Ekstensi Apigee diterapkan ke traffic API menggunakan panggilan ekstensi traffic.

Bagian berikut akan memandu Anda melakukan langkah-langkah untuk mengonfigurasi elemen utama Pemroses Ekstensi Apigee:

• Mengonfigurasi load balancer untuk layanan backend.
• Konfigurasi Pemroses Ekstensi Apigee.
• Konfigurasi ekstensi traffic.
• Menggunakan kebijakan dengan Extension Processor.

Sebelum memulai

Sebelum Anda mulai menyiapkan Pemroses Ekstensi Apigee, selesaikan tugas berikut:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Instal Google Cloud CLI.

   Setelah menginstal Google Cloud CLI, jalankan perintah gcloud components update untuk mendapatkan komponen gcloud terbaru.

2. Sediakan instance Apigee menggunakan versi 1-15-0-apigee-2 atau yang lebih baru, jika Anda belum melakukannya.

   Lihat versi instance di halaman Instance details di UI Apigee di konsol Google Cloud . Buka halaman Instances di konsol Google Cloud untuk memilih instance dan melihat detailnya:

   Buka Instances

   Anda dapat menggunakan Pemroses Ekstensi dengan organisasi Apigee Langganan atau Pay-as-you-go. Jika Anda tidak yakin apakah Anda menggunakan organisasi Apigee Berlangganan atau Bayar sesuai penggunaan, hubungi administrator organisasi Apigee Anda. Untuk mengetahui detail selengkapnya tentang penyediaan instance Apigee berbayar, lihat Sebelum memulai.

3. Pastikan Anda telah mengaktifkan VPC dan subnet di instance Apigee yang akan Anda gunakan. Buka halaman VPC Networks di konsol Google Cloud :

   Buka Jaringan VPC

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menginstal Pemroses Ekstensi Apigee, minta administrator untuk memberi Anda peran IAM berikut:

• Membuat dan mengelola akun layanan: Admin Akun Layanan (roles/iam.serviceAccountAdmin) di organisasi
• Membuat dan mengelola ekstensi layanan: Service Extensions Admin (roles/networkservices.serviceExtensionsAdmin) di organisasi
• Membuat dan mengelola grup endpoint jaringan (NEG): Compute Instance Admin (roles/compute.instanceAdmin) di organisasi
• Membuat dan mengelola resource jaringan: Compute Network Admin (roles/compute.networkAdmin) di organisasi
• Membuat dan mengelola layanan backend: Compute Load Balancer Admin (roles/compute.loadBalancerAdmin) di organisasi
• Membuat dan mengelola resource Apigee: Apigee Org Admin (roles/apigee.admin) di organisasi
• Membuat dan mengelola ekstensi traffic: Admin Ekstensi Layanan APIM Apigee (roles/apigee.apimServiceExtensionAdmin) di organisasi
• Melihat ekstensi traffic: Apigee APIM Service Extension Viewer (roles/apigee.apimServiceExtensionViewer) di organisasi
• Mengelola operasi yang berjalan lama: Agen Layanan Ekstensi Layanan APIM Apigee (roles/apigee.apimServiceExtensionServiceAgent) di agen layanan dalam project Google Cloud

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menetapkan variabel lingkungan

Di project Google Cloud yang berisi instance Apigee, gunakan perintah berikut untuk menetapkan variabel lingkungan:

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET

Dengan:

• PROJECT_ID adalah ID project dengan instance Apigee Anda.
• REGION adalah Google Cloud region instance Apigee Anda.
• INSTANCE adalah nama instance Apigee Anda.
• VPC_NETWORK_NAME adalah nama jaringan VPC di project Google Cloud yang ingin Anda gunakan untuk Pemroses Ekstensi Apigee.
• SUBNET adalah nama subnet di project Google Cloud Anda yang ingin Anda gunakan untuk Pemroses Ekstensi Apigee.

Untuk mengonfirmasi bahwa variabel lingkungan telah ditetapkan dengan benar, jalankan perintah berikut dan tinjau outputnya:

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET

Mengonfigurasi token autentikasi

Untuk mengonfigurasi token autentikasi, jalankan perintah berikut:

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

Mengonfigurasi load balancer untuk layanan backend

Bagian berikut menjelaskan langkah-langkah untuk menyiapkan Load Balancer Aplikasi eksternal global untuk layanan backend, menggunakan httpbin.org sebagai contoh:

1. Buat Load Balancer Aplikasi eksternal global.
2. Buat grup endpoint jaringan (NEG).
3. Buat layanan backend.
4. Buat peta URL.
5. Buat proxy target.
6. Buat aturan penerusan global.

Membuat Load Balancer Aplikasi eksternal global

Untuk membuat load balancer:

1. Tetapkan konfigurasi gcloud untuk menggunakan project Anda saat ini:

   gcloud config set project PROJECT_ID

   Dengan PROJECT_ID adalah ID project dengan instance Apigee Anda.

2. Buat alamat IP statis global:

   gcloud compute addresses create IP_ADDRESS --ip-version=IPV4 --global

   Dengan IP_ADDRESS adalah nama alamat IP yang ingin Anda buat. Nama harus cocok dengan ekspresi reguler (?:a-z?).

3. Dapatkan alamat IP dan simpan sebagai variabel lingkungan:

   IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)

   Dengan IP_ADDRESS adalah nama alamat IP yang Anda buat di langkah sebelumnya.

4. Buat sertifikat TLS untuk nip.io, layanan pihak ketiga yang menyediakan data DNS wildcard untuk alamat IP:

   gcloud compute ssl-certificates create SSL_CERT_NAME \
     --domains="nip.io"

   Dengan SSL_CERT_NAME adalah nama sertifikat yang ingin Anda buat.

Membuat grup endpoint jaringan (NEG)

Untuk membuat grup endpoint jaringan (NEG) untuk load balancer:

1. Buat NEG:

   gcloud compute network-endpoint-groups create NEG_NAME \
     --network-endpoint-type=INTERNET_FQDN_PORT \
     --default-port=443 \
     --global

   Dengan NEG_NAME adalah nama NEG yang ingin Anda buat.

2. Tambahkan endpoint untuk httpbin.org ke NEG:

   gcloud compute network-endpoint-groups update NEG_NAME \
     --add-endpoint=fqdn=httpbin.org,port=443 \
     --global

   Dengan NEG_NAME adalah nama NEG yang Anda buat di langkah sebelumnya.

Membuat layanan backend

Untuk membuat layanan backend yang diekspos oleh load balancer:

1. Buat layanan backend:

   gcloud compute backend-services create BACKEND_SERVICE_NAME \
     --load-balancing-scheme=EXTERNAL_MANAGED \
     --protocol=HTTPS \
     --global

   Ganti BACKEND_SERVICE_NAME dengan nama layanan backend yang ingin Anda buat.

2. Tambahkan NEG ke backend:

   gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
     --network-endpoint-group=NEG_NAME \
     --global-network-endpoint-group \
     --global

   Dengan:

   • BACKEND_SERVICE_NAME adalah nama layanan backend yang Anda buat di langkah sebelumnya.
   • NEG_NAME adalah nama NEG yang Anda buat di langkah sebelumnya.

Membuat peta URL

Untuk membuat peta URL antara load balancer dan layanan backend, gunakan perintah berikut:

gcloud compute url-maps create URL_MAP_NAME \
  --default-service BACKEND_SERVICE_NAME \
  --global

Dengan:

• URL_MAP_NAME adalah nama peta URL yang ingin Anda buat.
• BACKEND_SERVICE_NAME adalah nama layanan backend yang Anda buat di langkah sebelumnya.

Membuat proxy target

Untuk membuat proxy target agar load balancer memproses traffic ekstensi layanan, gunakan perintah berikut:

gcloud compute target-https-proxies create TARGET_PROXY_NAME \
  --global \
  --ssl-certificates SSL_CERT_NAME \
  --global-ssl-certificates \
  --url-map URL_MAP_NAME \
  --global-url-map

Dengan:

• TARGET_PROXY_NAME adalah nama proxy target yang ingin Anda buat.
• URL_MAP_NAME adalah nama peta URL yang Anda buat di langkah sebelumnya.
• SSL_CERT_NAME adalah nama sertifikat SSL yang Anda buat untuk nip.io di langkah sebelumnya.

Membuat aturan penerusan global

Untuk membuat aturan penerusan global bagi load balancer, gunakan perintah berikut:

gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --network-tier=PREMIUM \
  --address=IP_ADDRESS \
  --target-https-proxy=TARGET_PROXY_NAME \
  --ports=443 \
  --global

Dengan:

• FORWARDING_RULE_NAME adalah nama aturan penerusan yang ingin Anda buat.
• IP_ADDRESS adalah nama alamat IP endpoint NEG yang Anda buat di langkah sebelumnya.
• TARGET_PROXY_NAME adalah nama proxy target yang memproses traffic ekstensi.

Mengonfigurasi Pemroses Ekstensi Apigee

Bagian berikut menjelaskan langkah-langkah untuk menyiapkan Pemroses Ekstensi Apigee:

1. Buat lingkungan Apigee.
2. Buat proxy Extension Processor.

Membuat lingkungan Apigee

Catatan: Sebelum membuat lingkungan dan grup lingkungan baru, atau menggunakan resource yang ada untuk langkah ini, tinjau batasan pada lingkungan, grup lingkungan, dan proxy API dalam konfigurasi Extension Processor. Untuk mengetahui informasi selengkapnya, lihat Batasan.
1. Buat lingkungan Apigee menggunakan perintah berikut:

   curl -i -X POST -H  "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments" -H "Content-Type:application/json" -d \
       '{
           "name": "ENV_NAME",
           "displayName": "ENV_NAME",
           "state": "ACTIVE",
           "deploymentType": "PROXY",
           "apiProxyType": "PROGRAMMABLE",
           "type": "COMPREHENSIVE",
           "properties":
           {"property": [
               {
               "name": "apigee-service-extension-enabled",
               "value": "true"
               }
             ]
           }
       }'

   Dengan ENV_NAME adalah nama lingkungan yang Anda buat. Nama harus berisi antara 2 dan 32 karakter yang dapat berupa huruf kecil, angka, atau tanda hubung. Nama harus diawali dengan huruf dan tidak boleh diakhiri dengan tanda hubung. Nama harus berbeda dari nama lingkungan lainnya di organisasi Anda.

   Pastikan lingkungan dibuat:

   curl -i -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"

   Daftar lingkungan harus menyertakan lingkungan yang baru Anda buat.

2. Lampirkan lingkungan yang baru dibuat ke instance Apigee Anda:

   curl -i -X POST -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances/$INSTANCE/attachments" -H "Content-Type:application/json" -d \
       '{
           "environment": "ENV_NAME"
           }'

   Dengan ENV_NAME adalah nama lingkungan yang Anda buat di langkah sebelumnya.

   Operasi ini dapat memerlukan waktu hingga 10 menit.

3. Buat grup lingkungan Apigee:

   curl -H "Authorization: Bearer $TOKEN" -X POST \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups" -H "Content-Type:application/json" -d \
       '{
           "name": "ENV_GROUP_NAME",
           "hostnames": ["ENV_GROUP_HOSTNAME"]
           }'

   Dengan:

   • ENV_GROUP_NAME adalah nama grup lingkungan yang Anda buat.
   • ENV_GROUP_HOSTNAME adalah nama host grup lingkungan yang Anda buat. Nama host harus berupa nama domain yang sepenuhnya memenuhi syarat (FQDN).
     Catatan: Nama host tidak perlu dapat di-resolve.
4. Lampirkan lingkungan baru ke grup lingkungan baru:

   curl -H "Authorization: Bearer $TOKEN" -X POST\
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups/ENV_GROUP_NAME/attachments" -H "content-type:application/json" -d \
           '{
               "name": "ENV_GROUP_NAME",
               "environment": "ENV_NAME"
           }' 

   Dengan:

   • ENV_GROUP_NAME adalah nama grup lingkungan yang Anda buat.
   • ENV_NAME adalah nama lingkungan yang Anda buat di langkah sebelumnya.

Buat proxy Extension Processor

Proxy Extension Processor adalah proxy API Apigee yang digunakan untuk menerapkan kebijakan pengelolaan API ke traffic load balancer. Anda dapat membuat proxy tanpa target atau proxy yang mendukung Server-Sent Event (SSE). Untuk mempelajari lebih lanjut cara menggunakan SSE dengan Apigee, lihat Peristiwa yang dikirim server.

Untuk membuat proxy Apigee API yang akan digunakan dengan load balancer Extension Processor:

Tidak ada proxy target

1. Ikuti langkah-langkah di Membuat proxy API untuk membuat proxy Tanpa target dengan spesifikasi berikut:
   • Proxy template: Pilih No target.
   • Nama proxy: Masukkan nama proxy. Nama ini akan berfungsi sebagai ID untuk Pemroses Ekstensi.
   • Jalur dasar: Tetapkan jalur dasar yang Anda inginkan. Jalur tidak akan digunakan.

   Spesifikasi XML untuk proxy akan terlihat mirip dengan berikut ini:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <APIProxy revision="1" name="extproc-sample">
       <DisplayName/>
       <Description/>
       <CreatedAt>1739581781912</CreatedAt>
       <LastModifiedAt>1739582447868</LastModifiedAt>
       <BasePaths>/</BasePaths>
       <Policies></Policies>
       <ProxyEndpoints>
           <ProxyEndpoint>default</ProxyEndpoint>
       </ProxyEndpoints>
   </APIProxy>

2. Ikuti langkah-langkah di Men-deploy proxy API untuk men-deploy proxy ke lingkungan yang Anda buat sebelumnya.

Proxy yang mendukung SSE

1. Ikuti langkah-langkah di Membuat proxy API untuk membuat proxy Peristiwa yang dikirim server dengan spesifikasi berikut:
   • Proxy template: Pilih No target.
   • Nama proxy: Masukkan nama proxy.
   • Jalur dasar: Tetapkan jalur dasar yang Anda inginkan. Jalur tidak akan digunakan.

   Spesifikasi XML untuk proxy akan terlihat mirip dengan berikut ini:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <APIProxy revision="1" name="extproc-sample">
       <DisplayName/>
       <Description/>
       <CreatedAt>1739581781912</CreatedAt>
       <LastModifiedAt>1739582447868</LastModifiedAt>
       <BasePaths>/</BasePaths>
       <ProxyEndpoints>
           <ProxyEndpoint>default</ProxyEndpoint>
       </ProxyEndpoints>
   </APIProxy>

2. Konfigurasi EventFlow di proxy:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <APIProxy revision="1" name="extproc-sample">
       <DisplayName/>
       <Description/>
       <CreatedAt>1739581781912</CreatedAt>
       <LastModifiedAt>1739582447868</LastModifiedAt>
       <BasePaths>/</BasePaths>
       <ProxyEndpoints>
           <ProxyEndpoint>default</ProxyEndpoint>
           <EventFlow name="EventFlow" content-type="text/event-stream">
             <Response/>
           </EventFlow>
           <HTTPProxyConnection>
             <Properties/>
             <URL>https://httpbin.org/sse</URL>
           </HTTPProxyConnection>
       </ProxyEndpoints>
   </APIProxy>

3. Ikuti langkah-langkah di Men-deploy proxy API untuk men-deploy proxy ke lingkungan yang Anda buat sebelumnya.

Mengonfigurasi ekstensi traffic

Bagian ini menjelaskan cara mengonfigurasi ekstensi layanan traffic untuk Extension Processor Anda, menggunakan langkah-langkah berikut:

1. Buat ekstensi traffic dengan Extension Processor provisioning API.
2. Kirim permintaan ke load balancer.

Buat ekstensi traffic dengan Extension Processor Provisioning API

Pada langkah ini, buat ekstensi layanan traffic untuk Extension Processor menggunakan API penyediaan Extension Processor.

Buat ekstensi traffic menggunakan perintah berikut untuk memanggil API penyediaan Extension Processor:

curl -X POST -H  "Authorization: Bearer $TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions?apimServiceExtensionId=TRAFFIC_EXT_NAME \
    -H "Content-Type:application/json" -d \
    '{
      "extensionProcessor": "TARGET_PROXY_NAME"
      "lbForwardingRule": "LB_FORWARDING_RULE",
      "network" : "NETWORK",
      "networkConfigs": [
        {
          "region": "$REGION",
          "subnet": "project/my-project/regions/$REGION/subnetworks/$SUBNET"
        }
      ],
      "extensions": [
        {
          "name": "TARGET_PROXY_NAME",
          "matchCondition": "CEL_EXPRESSION",
          "failOpen": FAIL_OPEN,
          "hostname": "ENV_GROUP_HOSTNAME",
          "supportedEvents": [
            "REQUEST_HEADERS",
            "RESPONSE_HEADERS"
          ]
        }
      ]
    }'

Dengan:

• TRAFFIC_EXT_NAME adalah nama ekstensi traffic yang Anda buat.
• LB_FORWARDING_RULE adalah nama aturan penerusan yang Anda buat di langkah sebelumnya.
• NETWORK adalah nama jaringan yang Anda buat di langkah sebelumnya.
• TARGET_PROXY_NAME adalah nama proxy yang memproses traffic ekstensi.
• CEL_EXPRESSION adalah ekspresi Common Expression Language (CEL) yang ingin Anda gunakan untuk ekstensi traffic. Untuk mengetahui informasi selengkapnya tentang sintaksis CEL, lihat Referensi bahasa pencocok CEL.
• FAIL_OPEN adalah nilai boolean yang menentukan apakah ekstensi lalu lintas gagal terbuka atau tertutup. Nilai yang valid adalah true atau false.
• ENV_GROUP_HOSTNAME adalah nama host grup lingkungan yang Anda buat di langkah sebelumnya.
Catatan: Setelah ekstensi traffic dibuat, kolom name, lbForwardingRule, dan network tidak dapat diubah.

Operasi ini mungkin memerlukan waktu beberapa menit hingga selesai.

Mendapatkan detail ekstensi traffic

Untuk memverifikasi bahwa ekstensi layanan traffic berhasil dibuat, gunakan perintah berikut:

curl -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME"

Ganti TRAFFIC_EXT_NAME dengan nama ekstensi traffic yang baru saja Anda buat.

Responsnya akan terlihat mirip dengan berikut ini:

{
  "name": "my-traffic-extension",
  "extensionProcessor": "my-extension-processor",
  "lbForwardingRule": "https://www.googleapis.com/compute/v1/projects/my-project/global/forwardingRules/my-forwarding-rule",
  "network": "projects/my-project/global/networks/my-network",
  "networkConfigs": [
    {
      "region": "us-west1",
      "subnet": "projects/my-project/regions/us-west1/subnetworks/my-subnet"
    }
  ],
  "extensions": [
    {
      "name": "organizations/my-org/apis/my-api-proxy",
      "matchCondition": "request.url.contains('1234567890')",
      "failOpen": true,
      "hostname": "my-hostname.apigee.net",
      "supportedEvents": [
        "REQUEST_HEADERS",
        "RESPONSE_HEADERS"
      ]
    }
  ]
}

Memperbarui ekstensi traffic

Anda dapat memperbarui ekstensi info lalu lintas menggunakan parameter updateMask. Saat menggunakan parameter updateMask, Anda menentukan atribut resource yang ingin diperbarui dengan memberikan daftar yang dipisahkan koma. Atribut yang didukung untuk updateMask adalah:

• networkConfigs: pembaruan pada kolom region dan subnet.
  Catatan: Kolom ini hanya dapat diupdate untuk Load Balancer Aplikasi Global. Untuk Load Balancer Aplikasi Regional, networkConfigs tidak dapat diupdate; Anda harus menghapus dan membuat ulang ekstensi untuk mengubah konfigurasi jaringan.
• extensions: memperbarui kolom name, matchCondition, failOpen, hostname, dan supportedEvents.
• extensionProcessor: memperbarui kolom extensionProcessor.

Untuk memperbarui ekstensi traffic, gunakan perintah curl dengan metode PATCH. Anda dapat memperbarui beberapa atribut dengan menyertakannya dalam parameter kueri updateMask sebagai string yang dipisahkan koma (misalnya, ?updateMask=extensions,extensionProcessor).

Berikut beberapa contohnya:

Update networkConfigs (LB Global)

Untuk memperbarui atribut networkConfigs, gunakan perintah berikut:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=networkConfigs \
  -H "Content-Type:application/json" -d \
  '{
    "networkConfigs": [
      {
        "region": "REGION",
        "subnet": "projects/$PROJECT/regions/REGION/subnetworks/SUBNET"
      }
    ]
  }'

Dengan:

• TRAFFIC_EXT_NAME adalah nama ekstensi traffic Extension Processor yang akan diupdate.
• REGION adalah region yang diperbarui.
• SUBNET adalah subnet baru jaringan.

Update extensions

Untuk memperbarui atribut extensions, gunakan perintah berikut:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ]
  }'

Dengan:

• TRAFFIC_EXT_NAME adalah nama ekstensi traffic Extension Processor yang akan diupdate.
• TARGET_PROXY_NAME adalah nama proxy yang memproses traffic ekstensi.
• NEW_CEL_EXPRESSION adalah ekspresi CEL yang diperbarui.
• NEW_FAIL_OPEN adalah nilai boolean yang diperbarui untuk fail open.
• NEW_ENV_GROUP_HOSTNAME adalah nama host grup lingkungan.

Update extensionProcessor

Untuk memperbarui atribut extensionProcessor, gunakan perintah berikut:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

Dengan:

• TRAFFIC_EXT_NAME adalah nama ekstensi traffic Extension Processor yang akan diupdate.
• NEW_TARGET_PROXY_NAME adalah nama baru proxy yang memproses traffic ekstensi.

Memperbarui Beberapa Atribut (LB Global)

Untuk memperbarui atribut extensions dan extensionProcessor secara bersamaan, gunakan perintah berikut:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions,extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN,
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ],
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

Dengan:

• TRAFFIC_EXT_NAME adalah nama ekstensi traffic Extension Processor yang akan diupdate.
• TARGET_PROXY_NAME adalah nama proxy yang memproses traffic ekstensi.
• NEW_CEL_EXPRESSION adalah ekspresi CEL yang diperbarui.
• NEW_FAIL_OPEN adalah nilai boolean yang diperbarui untuk fail open.
• NEW_ENV_GROUP_HOSTNAME adalah nama host grup lingkungan.
• NEW_TARGET_PROXY_NAME adalah nama baru proxy yang memproses traffic ekstensi.

Mengirim permintaan ke load balancer

Untuk menguji penyiapan load balancer dan Extension Processor, kirim permintaan ke load balancer:

curl "https://LB_DOMAIN_NAME/get"

Dengan LB_DOMAIN_NAME adalah nama domain yang Anda gunakan untuk load balancer dan sertifikat SSL. Jika Anda menggunakan nip.io, nama domain akan terlihat mirip dengan IP_ADDRESS.nip.io.

Responsnya akan terlihat mirip dengan berikut ini:

{"status": 200,
  {
    "args": {},
    "headers": {
      ...
    },
    "origin": "173.93.50.108",
    "url": "https://httpbin.org/get"
  }
}

Menggunakan kebijakan dengan Pemroses Ekstensi

Bagian ini menjelaskan cara menggunakan kebijakan dengan Pemroses Ekstensi.

Dalam contoh ini, konfigurasi kebijakan VerifyAPIKey dan AssignMessage untuk Extension Processor. Kebijakan ini memvalidasi kunci API yang disertakan dalam permintaan ke Apigee dan menyisipkan Google token ke dalam header permintaan untuk panggilan ke layanan backend. Skenario ini akan berguna bagi penyedia API yang menggunakan Apigee Extension Processor untuk mengizinkan dan mengautentikasi permintaan ke layanan Apigee mereka serta menyisipkan token autentikasiGoogle yang diperlukan untuk layanan backend seperti Vertex AI secara lancar.

Menambahkan kebijakan VerifyAPIKey untuk validasi kunci API

Bagian berikut menjelaskan cara menggunakan kebijakan VerifyAPIKey untuk memvalidasi kunci API untuk panggilan ke layanan backend Anda menggunakan Extension Processor:

1. Lampirkan kebijakan VerifyAPIKey ke Extension Processor.
2. Buat produk API.
3. Buat Aplikasi developer dan kredensial Aplikasi.
4. Kirim permintaan ke load balancer menggunakan kunci API.

Melampirkan kebijakan VerifyAPIKey ke proxy

Untuk melampirkan kebijakan VerifyAPIKey ke proxy Extension Processor:

1. Di konsol Google Cloud , buka halaman Proxy Development > API Proxies.

   Buka Proxy API

2. Pilih proxy Extension Processor yang Anda buat di bagian Membuat pemroses ekstensi.
3. Klik tab Develop.
4. Di panel navigasi, klik di bagian Policies.
5. Pada dialog Create policy, pilih VerifyAPIKey dari daftar kebijakan.
6. Di panel VerifyAPIKey, isi kolom wajib diisi di bagian Name dan Display name menggunakan nilai berikut:
   • Name: Masukkan nama kebijakan. Contoh, VA-verify-api-key.
   • Display name: Masukkan nama kebijakan untuk digunakan di UI. Contoh, VA-verify-api-key.
7. Klik Create.

   Spesifikasi XML untuk kebijakan VerifyAPIKey yang disertakan dalam proxy Extension Processor akan terlihat mirip dengan berikut ini:

     <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <VerifyAPIKey continueOnError="false" enabled="true" name="VA-verify-api-key">
       <DisplayName>VA-verify-api-key</DisplayName>
       <Properties/>
       <APIKey ref="request.queryparam.x-api-key"/>
     </VerifyAPIKey>

8. Deploy revisi proxy baru.

Membuat produk API

Untuk membuat produk API dan mengonfigurasi set operasi API untuk layanan Anda:

1. Ikuti langkah-langkah di Membuat produk API untuk membuat produk API untuk layanan Anda. Anda dapat mengonfigurasi Detail produk untuk produk API sesuai keinginan Anda.
2. Ikuti langkah-langkah di Operasi untuk menambahkan set operasi API ke produk API, sesuai dengan spesifikasi berikut:
   • Sumber:

     Di konsol Google Cloud , buka halaman Distribution > API Products.

     Buka Produk API

     Pilih produk API yang Anda buat di langkah sebelumnya.
   • Operasi: Klik Edit dan konfigurasi jalur dan metode berikut:
     • Jalur: /get dengan Metode: GET
     • Jalur: /TARGET_PROXY_NAME dengan Metode: GET

       TARGET_PROXY_NAME adalah nama proxy yang memproses traffic ekstensi.

Membuat Aplikasi developer dan kredensial Aplikasi

Untuk membuat Aplikasi developer dan kredensial Aplikasi untuk produk API yang baru dibuat:

1. Buka halaman Pengelolaan API Apigee di konsol Google Cloud :

   Pengelolaan API Apigee

2. Buat developer:
   1. Pilih Distribusi > Developer.
   2. Di halaman Developers, klik + Create.
   3. Di halaman Tambahkan developer, lengkapi kolom yang wajib diisi menggunakan nilai apa pun yang Anda inginkan.
   4. Klik Tambahkan.
3. Membuat Aplikasi:
   1. Pilih Distribusi> Aplikasi.
   2. Di halaman Aplikasi, klik + Buat
   3. Di halaman Create App, isi kolom wajib diisi di bagian App Details menggunakan nilai berikut:
      • Nama aplikasi: Masukkan nama untuk Aplikasi. Misalnya, ext-proc-app
      • Developer: Pilih developer yang Anda buat pada langkah sebelumnya, atau developer lain dari daftar.
   4. Di bagian App Credentials, klik + Add Credential.
   5. Di bagian Kredensial, pilih Tidak Pernah dari kotak daftar Masa berlaku.
   6. Di bagian Produk, klik + Tambahkan produk untuk menampilkan panel Tambahkan Produk.
   7. Pilih produk API yang Anda buat di langkah sebelumnya.
   8. Klik Oke.
   9. Klik Tambahkan untuk menutup panel Tambahkan Produk.
   10. Klik Create.
4. Di halaman Detail Aplikasi, di bagian Kredensial, klik untuk menampilkan nilai Kunci.

   Salin nilai Key. Anda akan menggunakan kunci ini untuk melakukan panggilan API ke layanan Anda pada langkah selanjutnya.

5. Di halaman App Details, di bagian Credential, klik untuk menampilkan nilai App Secret.

Kirim permintaan ke load balancer menggunakan kunci API

Untuk menguji validasi kunci API, kirim permintaan ke load balancer menggunakan kunci API:

curl "https://LB_DOMAIN_NAME/get"

Dengan LB_DOMAIN_NAME adalah nama domain yang Anda gunakan untuk load balancer dan sertifikat SSL.

Respons gagal tanpa kunci API.

Kirim permintaan lain ke load balancer, menggunakan kunci API dalam permintaan:

curl "https://LB_DOMAIN_NAME/get?key=API_KEY"

Dengan:

• LB_DOMAIN_NAME adalah nama domain yang Anda gunakan untuk load balancer dan sertifikat SSL.
• API_KEY adalah kunci API dari kredensial Aplikasi Developer yang diungkapkan pada langkah sebelumnya.

Respons menunjukkan otorisasi yang berhasil untuk endpoint. Hal ini menunjukkan bahwa Extension Processor telah memvalidasi kunci API dan proxy Apigee kini dapat memproses permintaan.

Menambahkan kebijakan AssignMessage untuk Google autentikasi

Jika ingin menggunakan Extension Processor untuk menyediakan pengelolaan API bagi layanan yang diautentikasi Google, Anda dapat menyisipkan token akses Google atau token ID Google ke dalam permintaan yang dikirim ke layanan backend menggunakan kebijakan AssignMessage.

Bagian berikut menjelaskan cara menggunakan kebijakan AssignMessage untuk menyuntikkan token autentikasi ke dalam permintaan yang dikirim ke layanan backend menggunakan Extension Processor: Google

1. Lampirkan kebijakan AssignMessage ke proxy.
2. Kirim permintaan ke load balancer untuk menguji penyisipan token.

Melampirkan kebijakan AssignMessage ke proxy

Untuk menambahkan kebijakan AssignMessage ke proxy Anda:

1. Di konsol Google Cloud , buka halaman Proxy Development > API Proxies.

   Buka Proxy API

2. Pilih proxy Extension Processor yang Anda buat di bagian Membuat pemroses ekstensi.
3. Klik tab Develop.
4. Di panel navigasi, klik di bagian Policies.
5. Pada dialog Create policy, pilih AssignMessage dari daftar kebijakan.
6. Di panel Assign Message, selesaikan kolom wajib di bagian Name dan Display name menggunakan nilai berikut:
   • Name: Masukkan nama kebijakan. Contoh, AM-auth.
   • Display name: Masukkan nama kebijakan untuk ditampilkan di UI. Contoh, AM-auth.
7. Klik Create.
8. Di bawah elemen <Set>, tambahkan elemen turunan berikut:

   <Set>
       <Authentication>
       <HeaderName>Authorization</HeaderName>
       <GoogleAccessToken>
           <Scopes>
           <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
           </Scopes>
       </GoogleAccessToken>
       </Authentication>
   </Set>

9. Klik Simpan.
10. Deploy revisi baru menggunakan akun layanan Google .

Akun layanan membuat token akses Google dan menyisipkannya ke header permintaan untuk panggilan API ke layanan backend Google .

Mengirim permintaan ke load balancer untuk menguji penyisipan token

Untuk mengonfirmasi bahwa penyisipan token berfungsi, kirim permintaan ke load balancer:

curl "https://LB_DOMAIN_NAME/get"

Dengan LB_DOMAIN_NAME adalah nama domain yang Anda gunakan untuk load balancer dan sertifikat SSL.

Responsnya akan terlihat mirip dengan berikut ini:

{
  ...
  "headers": {
    "Accept": "*/*",
    "Authorization": "Bearer ya29.c.c0ASRK0Gbw03y9cfvxL11DxaRYBQUU18SmUP4Vu63OckHI5cX7wJ4DmGMG2vbDDS69HXJHqMj-lak4tcqOsJGmE65crn2gNuJLanXidwM8",
    "First": "1.0",
    "Host": "apigee-ext-proc-test.apigee.net",
    "Second": "1.0",
    "Sum": "2",
    "User-Agent": "curl/8.7.1",
    "X-Api-Key": "McYcHGR3PTSGLXExvKADwQ1JJeCjgPDUvAakCl0rJKCFaX0Y",
    "X-Cloud-Trace-Context": "0fd3dadc2a3c328fa968d5f5f1434c29/18300783092696918345"
  },
  ...
}

Respons menunjukkan penyisipan token autentikasi Google yang berhasil ke dalam header permintaan.

Dengan penerapan kebijakan AssignMessage yang berhasil, permintaan klien yang berhasil (berisi kunci API) ke Apigee dalam contoh skenario dimodifikasi lebih lanjut untuk menyertakan token autentikasi Google di header permintaan, seperti yang diperlukan oleh layanan backend yang diautentikasi Google.