Mengimpor spesifikasi OpenAPI

BERLAKU UNTUK: Semua tingkatan API Management

Artikel ini memperlihatkan cara mengimpor API backend spesifikasi OpenAPI ke Azure API Management menggunakan berbagai alat. Artikel ini juga menampilkan cara menguji API di API Management. Untuk informasi tentang dukungan versi OpenAPI, lihat Pembatasan impor API dan masalah yang diketahui.

Dalam artikel ini, Anda akan mempelajari cara:

• Mengimpor spesifikasi OpenAPI menggunakan portal Azure, Azure CLI, atau Azure PowerShell
• Menguji API di portal Microsoft Azure

Prasyarat

• Sebuah instans Manajemen API. Jika Anda belum memilikinya, selesaikan panduan memulai cepat berikut: Membuat instans Azure API Management.

• Azure CLI (antarmuka baris perintah Azure)

  • Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai menggunakan 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 Mengautentikasi ke Azure menggunakan Azure CLI.

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

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

• Azure PowerShell

  • Jika Anda memilih untuk menggunakan Azure PowerShell secara lokal:
    • Instal versi terbaru modul Az PowerShell.
    • Sambungkan ke akun Azure Anda menggunakan cmdlet Connect-AzAccount.
  • Jika Anda memilih untuk menggunakan Azure Cloud Shell:
    • Lihat Gambaran Umum Azure Cloud Shell untuk informasi selengkapnya.

Mengimpor API belakang

Untuk contoh ini, Anda mengimpor spesifikasi OpenAPI untuk API Petstore sumber terbuka. Anda dapat mengganti spesifikasi OpenAPI pilihan Anda.

Portal

1. Di Portal Microsoft Azure, navigasikan ke instans API Management Anda.

2. Di menu sebelah kiri, pilih API>+ Tambahkan API.

3. Di bagian Buat dari definisi, pilih OpenAPI.

   

4. Masukkan pengaturan API. Anda dapat mengatur nilai selama pembuatan atau mengkonfigurasinya nanti dengan masuk ke tab Pengaturan. Pengaturan dijelaskan dalam tutorial Mengimpor dan menerbitkan API pertama Anda.

5. Pilih Buat.

Azure CLI

Contoh berikut menggunakan perintah az apim api import untuk mengimpor spesifikasi OpenAPI dari URL yang ditentukan ke instans API Management bernama apim-hello-world. Untuk mengimpor menggunakan jalur ke spesifikasi, bukan URL, gunakan --specification-path parameter .

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

Setelah mengimpor API, Anda dapat memperbarui pengaturan dengan menggunakan perintah az apim api update .

PowerShell

Contoh berikut menggunakan cmdlet Import-AzApiManagementApi Azure PowerShell untuk mengimpor spesifikasi OpenAPI dari URL yang ditentukan ke instans API Management bernama apim-hello-world. Untuk mengimpor menggunakan jalur ke spesifikasi, bukan URL, gunakan -SpecificationPath parameter .

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Setelah mengimpor API, Anda dapat memperbarui pengaturan dengan menggunakan cmdlet Set-AzApiManagementApi .

Menampilkan dan mengedit spesifikasi OpenAPI

Di portal Microsoft Azure, gunakan editor spesifikasi OpenAPI untuk melihat, memvalidasi, atau mengedit spesifikasi untuk API yang Anda impor.

Untuk menggunakan editor spesifikasi OpenAPI:

1. Di portal Microsoft Azure, navigasikan ke instans API Management Anda.
2. Di menu sebelah kiri, di bawah API, pilih API><API Anda>>Semua operasi.
3. Pada tab Desain , di Frontend, pilih editor Spesifikasi OpenAPI (ikon pensil). Anda dapat membuka spesifikasi dalam format JSON atau YAML.
4. Tinjau atau edit spesifikasi sesuai kebutuhan. Simpan perubahan Anda.

Memvalidasi terhadap skema spesifikasi OpenAPI

Anda dapat mengonfigurasi kebijakan validasi API Management untuk memvalidasi permintaan dan respons atau elemennya terhadap skema dalam spesifikasi OpenAPI. Misalnya, gunakan kebijakan validasi konten untuk memvalidasi ukuran atau konten isi permintaan atau respons.

Menguji API baru di portal

Anda dapat memanggil operasi langsung dari portal Microsoft Azure, yang menyediakan cara mudah untuk melihat dan menguji operasi API.

1. Memilih API yang Anda buat di langkah sebelumnya.

2. Pilih tab Uji.

3. Pilih operasi.

   Halaman ini menampilkan bidang untuk parameter kueri dan bidang untuk header.

   Catatan

   Di konsol pengujian, API Management secara otomatis mengisi tajuk Ocp-Apim-Subscription-Key, dan mengonfigurasi kunci berlangganan semua-akses bawaan. Kunci ini memungkinkan akses ke setiap API dalam instans API Management. Untuk menampilkan header Ocp-Apim-Subscription-Key secara opsional, pilih ikon "mata" di samping Permintaan HTTP.

4. Bergantung pada operasi, masukkan nilai parameter kueri, nilai header, atau isi permintaan. Pilih Kirim.

   Ketika pengujian berhasil, backend merespons dengan kode respons HTTP yang berhasil dan beberapa data.

   Kiat

   Secara default, konsol pengujian mengirimkan permintaan ke proksi CORS API Management, yang meneruskan permintaan ke instans API Management, yang kemudian meneruskannya ke backend. Proksi ini menggunakan alamat IP publik 13.91.254.72 dan hanya dapat menjangkau titik akhir publik.

   Jika Anda ingin mengirim permintaan langsung dari browser ke layanan API Management, pilih Lewati proksi CORS. Gunakan opsi ini saat Anda ingin menggunakan konsol uji dan gateway API Management Anda terisolasi dari jaringan atau tidak mengizinkan lalu lintas dari proksi CORS.

Untuk menyelesaikan kesalahan API, silakan lihat Tutorial: Menyelesaikan kesalahan API menggunakan pelacakan permintaan.

Menambahkan API lainnya

Anda dapat menyusun API dari API yang diekspos oleh layanan yang berbeda, termasuk:

• Spesifikasi OpenAPI
• API SOAP
• Sebuah API GraphQL
• Aplikasi Web yang dihosting di Azure App Service
• Azure Functions
• Azure Logic Apps
• Azure Service Fabric

Catatan

Saat Anda mengimpor API, operasi ditambahkan ke API Anda saat ini.

Untuk menambahkan API ke API yang ada:

1. Buka instans Azure API Management Anda di portal Microsoft Azure:

   

2. Pilih API di halaman Gambaran Umum, atau pilih API API> di menu bilah samping.

   

3. Pilih elipsis (...) di samping API yang ingin Anda tambahkan API lain.

4. Pilih Impor dari menu konteks:

   

5. Pilih layanan untuk mengimpor API.

Konten terkait

• Batasan impor API
• Mengimpor spesifikasi OpenAPI
• Mengimpor API SOAP
• Mengimpor SOAP API dan mengonversinya ke REST
• Impor API Layanan Aplikasi
• Mengimpor API aplikasi kontainer
• Mengimpor API WebSocket
• Mengimpor sebuah API GraphQL
• Mengimpor skema GraphQL dan menyiapkan penyelesai bidang
• Mengimpor API aplikasi fungsi
• Mengimpor API aplikasi logika
• Mengimpor layanan Service Fabric
• Mengimpor MICROSOFT Foundry API
• Mengimpor Azure OpenAI API
• Mengimpor LLM API
• Mengimpor API OData
• Mengekspor REST API sebagai server MCP
• Mengekspos server MCP yang ada
• Mengimpor API agen A2A
• Mengimpor metadata SAP OData
• Mengimpor API gRPC
• Edit API