Tutorial: Membuat dan menerbitkan produk

BERLAKU UNTUK: Semua tingkatAN API Management

Dalam Azure API Management, sebuah produk berisi satu atau beberapa API, kuota penggunaan, dan ketentuan penggunaan. Setelah produk diterbitkan, pengembang dapat berlangganan produk dan mulai menggunakan API produk.

Tip

Tim API dapat menggunakan fitur ini di ruang kerja. Ruang kerja menyediakan akses administratif terisolasi ke API dan lingkungan runtime API mereka sendiri.

Dalam tutorial ini, Anda akan mempelajari cara:

• Membuat dan menerbitkan produk
• Tambahkan API ke produk
• Mengakses API produk

Prasyarat

• Mempelajari terminologi Azure API Management.
• Menyelesaikan mulai cepat berikut: Membuat instans Azure API Management.
• Selain itu, selesaikan tutorial berikut: Mengimpor dan menerbitkan API pertama Anda.

Membuat dan menerbitkan produk

Portal

1. Masuk ke portal Microsoft Azure, dan buka instans API Management Anda.

2. Di panel navigasi kiri, pilih Produk> + Tambahkan.

   

3. Di jendela Tambahkan produk, masukkan nilai yang dijelaskan dalam tabel berikut untuk membuat produk Anda.

   

   Nama	Deskripsi
   Nama tampilan	Nama yang Anda inginkan untuk ditampilkan di portal pengembang.
   Deskripsi	Memberikan informasi tentang produk seperti tujuannya, API yang mendapatkan aksesnya, dan detail lainnya.
   Status	Pilih Diterbitkan jika Anda ingin menerbitkan produk ke portal pengembang. Sebelum API dalam produk dapat ditemukan oleh pengembang, produk harus diterbitkan. Secara default, produk baru tidak diterbitkan.
   Membutuhkan langganan	Pilih apakah pengguna diharuskan berlangganan untuk menggunakan produk (produk dilindungi) dan kunci langganan harus digunakan untuk mengakses API produk. Jika langganan tidak diperlukan (produk terbuka), kunci langganan tidak diperlukan untuk mengakses API produk. Lihat Akses ke API produk nanti di artikel ini.
   Membutuhkan persetujuan	Ambil pilihan ini, jika Anda ingin administrator meninjau dan menerima atau menolak upaya berlangganan untuk produk ini. Jika tidak dipilih, upaya berlangganan disetujui secara otomatis.
   Batas jumlah langganan	Secara opsional, batasi jumlah beberapa langganan simultan. Nilai minimum: 1
   Istilah hukum	Anda dapat menyertakan ketentuan penggunaan produk yang harus diterima oleh pelanggan untuk menggunakan produk tersebut.
   API	Pilih satu atau beberapa API. Anda juga dapat menambahkan API setelah membuat produk. Untuk informasi selengkapnya, lihat Menambahkan API ke produk pada bagian berikutnya di artikel ini. Jika produk terbuka (tidak memerlukan langganan), Anda hanya dapat menambahkan API yang tidak terkait dengan produk terbuka lain.

4. Pilih Buat untuk membuat produk baru Anda.

Perhatian

Berhati-hatilah saat mengonfigurasi produk yang tidak memerlukan langganan. Konfigurasi ini mungkin terlalu permisif dan dapat membuat API produk lebih rentan terhadap ancaman keamanan API tertentu.

Azure CLI

Untuk mulai menggunakan Azure CLI:

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

Untuk membuat produk, jalankan perintah az apim product create:

az apim product create --resource-group apim-hello-word-resource-group \
    --product-name "Contoso product" --product-id contoso-product \
    --service-name apim-hello-world --subscription-required true \
    --state published --description "This is a test."

Anda dapat menentukan berbagai nilai untuk produk Anda:

Parameter	Deskripsi
--product-name	Nama yang Anda inginkan untuk ditampilkan di portal pengembang.
--description	Memberikan informasi tentang produk seperti tujuannya, API yang mendapatkan aksesnya, dan detail lainnya.
--state	Pilih diterbitkan jika Anda ingin menerbitkan produk ke portal pengembang. Sebelum API dalam produk dapat ditemukan oleh pengembang, produk harus diterbitkan. Secara default, produk baru tidak diterbitkan.
--subscription-required	Pilih apakah pengguna diharuskan berlangganan untuk menggunakan produk (produk dilindungi) atau langganan tidak diperlukan (produk terbuka). Lihat Akses ke API produk nanti di artikel ini.
--approval-required	Ambil pilihan ini, jika Anda ingin administrator meninjau dan menerima atau menolak upaya berlangganan untuk produk ini. Jika tidak dipilih, upaya berlangganan disetujui secara otomatis.
--subscriptions-limit	Batasi jumlah beberapa langganan simultan secara opsional.
--legal-terms	Anda dapat menyertakan ketentuan penggunaan produk yang harus diterima oleh pelanggan untuk menggunakan produk tersebut.

Perhatian

Berhati-hatilah saat mengonfigurasi produk yang tidak memerlukan langganan. Konfigurasi ini mungkin terlalu permisif dan dapat membuat API produk lebih rentan terhadap ancaman keamanan API tertentu.

Untuk melihat produk Anda saat ini, gunakan perintah az apim product list:

az apim product list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Anda dapat menghapus produk dengan menggunakan perintah az apim product delete:

az apim product delete --product-id contoso-product \
    --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --delete-subscriptions true

Tambahkan lebih banyak konfigurasi

Lanjutkan mengonfigurasi produk setelah menyimpannya. Dalam instans API Management Anda, pilih produk dari jendela Produk. Tambahkan atau perbarui:

Item	Deskripsi
Pengaturan	Metadata dan status produk
API	API yang terkait dengan produk
Kebijakan	Kebijakan yang diterapkan ke API produk
Kontrol akses	Visibilitas produk untuk pengembang atau tamu
Langganan	Pelanggan produk

Tambahkan API ke produk

Produk adalah kumpulan dari satu atau beberapa API. Anda dapat menyertakan sejumlah API dan menawarkannya kepada pengembang melalui portal pengembang. Selama pembuatan produk, Anda dapat menambahkan satu atau beberapa API yang sudah ada. Anda juga dapat menambahkan API ke produk nanti, baik dari halaman Pengaturan Produk atau saat membuat API.

Tambahkan API ke produk yang sudah ada

Portal

1. Di navigasi kiri instans API Management Anda, pilih Produk.
2. Pilih produk, lalu pilih API.
3. Pilih + Tambahkan API.
4. Pilih satu atau beberapa API, lalu Pilih.

Azure CLI

1. Untuk melihat API terkelola Anda, gunakan perintah az apim api list:

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

2. Untuk menambahkan API ke produk Anda, jalankan perintah az apim product api add:

   az apim product api add --resource-group apim-hello-word-resource-group \
       --api-id petstore-api --product-id contoso-product \
       --service-name apim-hello-world
   

3. Verifikasi penambahan dengan menggunakan perintah az apim product api list:

   az apim product api list --resource-group apim-hello-word-resource-group \
       --product-id contoso-product --service-name apim-hello-world --output table
   

Anda dapat menghapus API dari produk dengan menggunakan perintah az apim product api delete:

az apim product api delete --resource-group apim-hello-word-resource-group \
    --api-id petstore-api --product-id contoso-product \
    --service-name apim-hello-world

Akses ke API produk

Setelah Anda menerbitkan produk, pengembang dapat mengakses API. Tergantung pada bagaimana produk dikonfigurasi, mereka mungkin perlu berlangganan produk untuk akses.

• Produk yang dilindungi - Pengembang harus terlebih dahulu berlangganan produk yang dilindungi untuk mendapatkan akses ke API produk. Saat berlangganan, mereka akan mendapatkan kunci langganan yang sesuai untuk API dalam produk tersebut. Jika Anda membuat instans API Management, Anda telah menjadi administrator, jadi Anda berlangganan setiap produk secara default. Untuk informasi selengkapnya, lihat Langganan di Azure API Management.

  Ketika klien membuat permintaan API dengan kunci langganan produk yang valid, API Management memproses permintaan dan mengizinkan akses dalam konteks produk. Kebijakan dan aturan kontrol akses yang dikonfigurasi untuk produk dapat diterapkan.

  Tip

  Anda dapat membuat atau memperbarui langganan pengguna ke produk dengan kunci langganan kustom melalui perintah REST API atau PowerShell.

• Produk terbuka - Pengembang dapat mengakses API produk terbuka tanpa kunci langganan. Namun, Anda dapat mengonfigurasi mekanisme lain untuk mengamankan akses klien ke API, termasuk OAuth 2.0, sertifikat klien, dan membatasi alamat IP pemanggil.

  Catatan

  Produk terbuka tidak tercantum di portal pengembang untuk dipelajari atau dilanggani pengembang. Mereka hanya terlihat oleh grup Administrator . Anda harus menggunakan mekanisme lain untuk memberi tahu pengembang tentang API yang dapat diakses tanpa kunci langganan.

  Saat klien membuat permintaan API tanpa kunci langganan:

  • API Management memeriksa apakah API terkait dengan produk terbuka. API dapat dikaitkan dengan paling banyak satu produk terbuka.

  • Jika ada produk terbuka, maka API akan memproses permintaan dalam konteks produk terbuka tersebut. Aturan kebijakan dan kontrol akses yang dikonfigurasi untuk produk terbuka dapat diterapkan.

Untuk informasi selengkapnya, lihat Cara API Management menangani permintaan dengan atau tanpa kunci langganan.

Langkah berikutnya

Dalam tutorial ini, Anda mempelajari cara:

• Membuat dan menerbitkan produk
• Tambahkan API ke produk
• Mengakses API produk

Melanjutkan ke tutorial berikutnya:

Buat API kosong dan respons API tiruan

Dalam artikel ini, Anda menggunakan Terraform untuk membuat instans Azure API Management, API, produk, grup, dan asosiasi antara produk dan API, serta produk dan grup.

Terraform memungkinkan definisi, pratinjau, dan penyebaran infrastruktur cloud. Menggunakan Terraform, Anda membuat file konfigurasi menggunakan sintaksis HCL. Sintaksis HCL memungkinkan Anda menentukan penyedia cloud - seperti Azure - dan elemen yang membentuk infrastruktur cloud Anda. Setelah membuat file konfigurasi, Anda membuat rencana eksekusi yang memungkinkan Anda untuk melihat pratinjau perubahan infrastruktur Anda sebelum disebarkan. Setelah memverifikasi perubahan, Anda menerapkan rencana eksekusi untuk menyebarkan infrastruktur.

• Tentukan versi Terraform yang diperlukan dan penyedia yang diperlukan.
• Tentukan variabel untuk awalan nama grup sumber daya, lokasi grup sumber daya, serta format dan nilai konten untuk impor definisi API.
• Buat grup sumber daya dengan nama acak.
• Buat layanan API Management dengan nama acak.
• Buat API dengan nama acak.
• Buat produk dengan nama acak di layanan API Management.
• Buat grup dengan nama acak.
• Kaitkan API dengan produk.
• Kaitkan grup dengan produk.
• Keluarkan nilai acak seperti nama grup sumber daya, layanan API Management, API, produk, dan grup.

Prasyarat

• Buat akun Azure dengan langganan aktif. Anda dapat membuat akun secara gratis.

• Menginstal dan mengonfigurasi Terraform.

Menerapkan kode Terraform

Catatan

Kode sampel untuk artikel ini terletak di repositori GitHub Azure Terraform. Anda dapat melihat file log yang berisi hasil pengujian dari terraform versi saat ini dan sebelumnya.

Lihat artikel dan kode sampel lainnya yang memperlihatkan cara menggunakan Terraform untuk mengelola sumber daya Azure.

1. Buat direktori untuk menguji dan menjalankan contoh kode Terraform dan menjadikannya direktori saat ini.

2. Buat file bernama main.tf, dan sisipkan kode berikut:

   resource "random_pet" "rg_name" {
     prefix = var.resource_group_name_prefix
   }
   
   resource "azurerm_resource_group" "rg" {
     location = var.resource_group_location
     name     = random_pet.rg_name.id
   }
   
   resource "random_string" "apim_service_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management" "apim_service" {
     name                = "${random_string.apim_service_name.result}-apim-service"
     location            = azurerm_resource_group.rg.location
     resource_group_name = azurerm_resource_group.rg.name
     publisher_name      = "Example Publisher"
     publisher_email     = "publisher@example.com"
     sku_name            = "Developer_1"
     tags = {
       Environment = "Example"
     }
     policy {
       xml_content = <<XML
       <policies>
         <inbound />
         <backend />
         <outbound />
         <on-error />
       </policies>
   XML
     }
   }
   
   resource "random_string" "api_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "random_string" "content_value" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_api" "api" {
     name                = "${random_string.api_name.result}-api"
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     revision            = "1"
     display_name        = "${random_string.api_name.result}-api"
     path                = "example"
     protocols           = ["https", "http"]
     description         = "An example API"
     import {
       content_format = var.open_api_spec_content_format
       content_value  = var.open_api_spec_content_value
     }
   }
   
   resource "random_string" "product_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_product" "product" {
     product_id            = "${random_string.product_name.result}-product"
     resource_group_name   = azurerm_resource_group.rg.name
     api_management_name   = azurerm_api_management.apim_service.name
     display_name          = "${random_string.product_name.result}-product"
     subscription_required = true
     approval_required     = false
     published             = true
     description           = "An example Product"
   }
   
   resource "random_string" "group_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_group" "group" {
     name                = "${random_string.group_name.result}-group"
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     display_name        = "${random_string.group_name.result}-group"
     description         = "An example group"
   }
   
   resource "azurerm_api_management_product_api" "product_api" {
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     product_id          = azurerm_api_management_product.product.product_id
     api_name            = azurerm_api_management_api.api.name
   }
   
   resource "azurerm_api_management_product_group" "product_group" {
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     product_id          = azurerm_api_management_product.product.product_id
     group_name          = azurerm_api_management_group.group.name
   }
   

3. Buat file bernama outputs.tf, dan sisipkan kode berikut:

   output "resource_group_name" {
     value = azurerm_resource_group.rg.name
   }
   
   output "apim_service_name" {
     value = azurerm_api_management.apim_service.name
   }
   
   output "api_name" {
     value = azurerm_api_management_api.api.name
   }
   
   output "product_name" {
     value = azurerm_api_management_product.product.product_id
   }
   
   output "group_name" {
     value = azurerm_api_management_group.group.name
   }
   
   output "service_id" {
     description = "The ID of the API Management Service created"
     value       = azurerm_api_management.apim_service.id
   }
   
   output "gateway_url" {
     description = "The URL of the Gateway for the API Management Service"
     value       = azurerm_api_management.apim_service.gateway_url
   }
   
   output "service_public_ip_addresses" {
     description = "The Public IP addresses of the API Management Service"
     value       = azurerm_api_management.apim_service.public_ip_addresses
   }
   
   output "api_outputs" {
     description = "The IDs, state, and version outputs of the APIs created"
     value = {
       id             = azurerm_api_management_api.api.id
       is_current     = azurerm_api_management_api.api.is_current
       is_online      = azurerm_api_management_api.api.is_online
       version        = azurerm_api_management_api.api.version
       version_set_id = azurerm_api_management_api.api.version_set_id
     }
   }
   
   output "product_id" {
     description = "The ID of the Product created"
     value       = azurerm_api_management_product.product.id
   }
   
   output "product_api_id" {
     description = "The ID of the Product/API association created"
     value       = azurerm_api_management_product_api.product_api.id
   }
   
   output "product_group_id" {
     description = "The ID of the Product/Group association created"
     value       = azurerm_api_management_product_group.product_group.id
   }
   

4. Buat file bernama providers.tf, dan sisipkan kode berikut:

   terraform {
     required_version = ">=1.0"
     
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = "~>3.0"
       }
       random = {
         source  = "hashicorp/random"
         version = "~>3.0"
       }
     }
   }
   
   provider "azurerm" {
     features {}
   }
   

5. Buat file bernama variables.tf, dan sisipkan kode berikut:

   variable "resource_group_name_prefix" {
     type        = string
     default     = "rg"
     description = "Prefix of the resource group name that's combined with a random ID so name is unique in your Azure subscription."
   }
   
   variable "resource_group_location" {
     type        = string
     default     = "eastus"
     description = "Location of the resource group."
   }
   
   variable "open_api_spec_content_format" {
     type        = string
     default     = "swagger-link-json"
     description = "The format of the content from which the API Definition should be imported. Possible values are: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
     validation {
       condition     = contains(["openapi", "openapi+json", "openapi+json-link", "openapi-link", "swagger-json", "swagger-link-json", "wadl-link-json", "wadl-xml", "wsdl", "wsdl-link"], var.open_api_spec_content_format)
       error_message = "open_api_spec_content_format must be one of the following: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
     }
   }
   
   variable "open_api_spec_content_value" {
     type        = string
     default     = "https://petstore3.swagger.io/api/v3/openapi.json"
     description = "The Content from which the API Definition should be imported. When a content_format of *-link-* is specified this must be a URL, otherwise this must be defined inline."
   }
   

Inisialisasi Terraform

Jalankan terraform init untuk menginisialisasi penyebaran Terraform. Perintah ini mengunduh penyedia Azure yang diperlukan untuk mengelola sumber daya Azure Anda.

terraform init -upgrade

Poin utama:

• Parameter -upgrade meningkatkan plugin penyedia yang diperlukan ke versi terbaru yang sesuai dengan batasan versi konfigurasi.

Buat rencana eksekusi Terraform

Jalankan terraform plan untuk membuat rencana eksekusi.

terraform plan -out main.tfplan

Poin utama:

• Perintah terraform plan membuat rencana eksekusi, tetapi tidak menjalankannya. Perintah ini justru menentukan tindakan yang diperlukan untuk membuat konfigurasi yang ditentukan dalam file konfigurasi Anda. Pola ini memungkinkan Anda memastikan apakah rencana eksekusi telah sesuai dengan ekspektasi Anda sebelum membuat perubahan pada sumber daya aktual.
• Parameter -out opsional memungkinkan Anda menentukan file output untuk rencana. Menggunakan parameter -out memastikan bahwa rencana yang Anda tinjau benar-benar sesuai dengan yang diterapkan.

Terapkan rencana eksekusi Terraform

Jalankan terraform apply untuk menerapkan rencana eksekusi ke infrastruktur cloud Anda.

terraform apply main.tfplan

Poin utama:

• Contoh terraform apply perintah mengasumsikan Anda sebelumnya menjalankan terraform plan -out main.tfplan.
• Jika Anda menentukan nama file yang berbeda untuk parameter -out, gunakan nama file yang sama dalam panggilan ke terraform apply.
• Jika Anda tidak menggunakan parameter -out, panggil terraform apply tanpa parameter apa pun.

Memverifikasi hasil

Jalankan az apim show untuk melihat Azure API Management:

az apim show --<apim_service_name> --<resource_group_name>

Membersihkan sumber daya

Ketika Anda tidak lagi membutuhkan sumber daya yang dibuat melalui Terraform, lakukan langkah-langkah berikut:

1. Jalankan terraform plan dan tentukan bendera destroy.

   terraform plan -destroy -out main.destroy.tfplan
   

   Poin utama:

   • Perintah terraform plan membuat rencana eksekusi, tetapi tidak menjalankannya. Perintah ini justru menentukan tindakan yang diperlukan untuk membuat konfigurasi yang ditentukan dalam file konfigurasi Anda. Pola ini memungkinkan Anda memastikan apakah rencana eksekusi telah sesuai dengan ekspektasi Anda sebelum membuat perubahan pada sumber daya aktual.
   • Parameter -out opsional memungkinkan Anda menentukan file output untuk rencana. Menggunakan parameter -out memastikan bahwa rencana yang Anda tinjau benar-benar sesuai dengan yang diterapkan.

2. Jalankan terraform apply untuk menerapkan rencana eksekusi.

   terraform apply main.destroy.tfplan
   

Memecahkan masalah Terraform pada Azure

Memecahkan masalah umum saat menggunakan Terraform di Azure.

Langkah berikutnya

Buat RESPONS API dan API tiruan kosong.