Tutorial: Mengimpor dan memublikasikan API pertama Anda

BERLAKU UNTUK: Semua lapisan API Management

Tutorial ini menunjukkan cara mengimpor API backend spesifikasi OpenAPI dalam format JSON ke dalam Azure API Management. Untuk contoh ini, Anda mengimpor API open source Petstore.

Kiat

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

Saat Anda mengimpor API backend ke API Management, API API Management Anda menjadi gateway untuk API backend. Anda dapat menyesuaikan gateway dengan kebutuhan Anda di API Management tanpa mengubah API backend. Untuk informasi selengkapnya, lihat Mengubah dan melindungi API Anda.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Mengimpor API ke API Management
  • Melihat dan mengubah pengaturan API
  • Menguji API di Azure portal
  • Merutekan permintaan API melalui API Management

Setelah mengimpor, Anda dapat mengelola API di Azure portal.

Screenshot dari API baru di API Management di portal.

Prasyarat

Buka instans API Management Anda

  1. Di portal Microsoft Azure, cari dan pilih layanan API Management:

    Screenshot yang memperlihatkan layanan API Management di hasil pencarian.

  2. Pada halaman API Management services, pilih instans API Management Anda:

    Screenshot yang menunjukkan instans API Management pada halaman layanan API Management.

Mengimpor dan menerbitkan API backend

Bagian ini menunjukkan cara mengimpor dan menerbitkan API backend spesifikasi OpenAPI.

  1. Dalam instans API Management Anda, di bawah APIs di menu bilah samping, pilih APIs.

  2. Pilih ubin OpenAPI.

  3. Di jendela Buat dari spesifikasi OpenAPI, pilih Penuh.

  4. Masukkan nilai dari tabel berikut ini.

    Anda dapat mengatur nilai API selama pembuatan atau nanti dengan masuk ke tab Pengaturan.

    Cuplikan layar pembuatan API di portal.

    Pengaturan Nilai Deskripsi
    spesifikasi OpenAPI https://petstore3.swagger.io/api/v3/openapi.json atau https://petstore.swagger.io/v2/swagger.json Menentukan layanan backend yang mengimplementasikan API dan operasi yang didukung API.

    URL layanan backend muncul nanti sebagai URL Layanan web di halaman Pengaturan API.

    Setelah mengimpor, Anda dapat menambahkan, mengedit, mengganti nama, atau menghapus operasi dalam spesifikasi.
    Menyertakan parameter kueri dalam templat operasi Dipilih (default) Menentukan apakah akan mengimpor parameter kueri yang diperlukan dalam spesifikasi sebagai parameter templat di API Management.
    Nama tampilan Setelah Anda memasukkan URL spesifikasi OpenAPI, API Management mengisi bidang ini berdasarkan JSON. Nama ditampilkan di portal pengembang.
    Nama Setelah Anda memasukkan URL spesifikasi OpenAPI, API Management mengisi bidang ini berdasarkan JSON. Nama unik untuk API.
    Deskripsi Setelah Anda memasukkan URL spesifikasi OpenAPI, API Management mengisi bidang ini berdasarkan JSON. Deskripsi opsional API.
    Skema URL HTTPS Protokol mana yang dapat access API.
    Sufiks URL API petstore Akhiran ditambahkan ke URL dasar untuk layanan API Management. API Management membedakan dan merutekan API dengan akhirannya, sehingga akhiran harus unik untuk setiap API untuk publisher tertentu. Pelajari selengkapnya tentang cara API Management merutekan permintaan.
    Tagar Tag untuk mengatur API untuk pencarian, pengelompokan, atau pemfilteran.
    Produk Tidak Terbatas Asosiasi dari satu atau lebih API. Dalam tingkat tertentu, instans API Management dilengkapi dengan dua produk sampel: Starter dan Unlimited. Anda menerbitkan API di portal pengembang dengan mengaitkan API dengan produk.

    Anda dapat menyertakan beberapa API dalam produk dan menawarkan langganan produk kepada pengembang melalui portal pengembang. Untuk menambahkan API ini ke produk lain, ketik atau pilih nama produk. Ulangi langkah ini untuk menambahkan API ke beberapa produk. Anda juga dapat menambahkan API ke produk nanti dari halaman Pengaturan.

    Untuk informasi selengkapnya tentang produk, lihat Membuat dan menerbitkan produk.
    Gateway Terkelola Gerbang API yang mengekspos API. Bidang ini hanya tersedia di layanan tingkat Pengembang dan Premium.

    Managed menunjukkan gateway yang dibangun ke dalam layanan API Management dan dihosting oleh Microsoft di Azure. Gateway yang dihosting sendiri hanya tersedia di tingkat layanan Premium dan Pengembang. Anda dapat menyebarkannya lokal atau di cloud lainnya.

    Jika Anda tidak memilih gateway apa pun, API tidak tersedia dan permintaan API Anda tidak berhasil.
    Versi API ini? Pilih atau batalkan pilihan Untuk informasi selengkapnya, lihat Menerbitkan beberapa versi API Anda.

  5. Pilih Buat untuk membuat API Anda.

Jika Anda mengalami masalah saat mengimpor definisi API, lihat Pembatasan impor API dan masalah yang diketahui.

Melihat dan mengubah pengaturan API

Setelah mengimpor API, Anda dapat melihat dan memodifikasi pengaturan dan operasinya di Azure portal.

  1. Dalam instans API Management Anda, di bawah APIs di menu bilah samping, pilih APIs.

  2. Pilih API yang Diimpor (misalnya, Swagger Petstore). Screenshot pengaturan API di portal, pada API Management.

  3. Pilih tab Desain untuk melihat dan memodifikasi operasi API dalam spesifikasi OpenAPI, termasuk:

    • Detail operasi seperti URL, metode, dan deskripsi
    • Definisi permintaan dan respons
    • Kebijakan untuk mengubah permintaan dan respons

  4. Pilih tab Pengaturan untuk melihat dan mengubah detail konfigurasi API, termasuk:

    • Nama tampilan, nama, dan deskripsi
    • URL layanan web (layanan backend), skema URL, dan akhiran URL API
    • Produk, tag, dan penerapan versi
    • Pengaturan tingkat lanjut lainnya, seperti persyaratan langganan, keamanan, dan pemantauan

Saat Anda melalui tutorial API Management, Anda mempelajari selengkapnya tentang mengonfigurasi pengaturan API. Anda dapat memperbarui pengaturan ini kapan saja untuk menyesuaikan konfigurasi API Anda.

Menguji API baru di Azure portal

Anda dapat memanggil operasi API langsung dari Azure portal, yang menyediakan cara mudah untuk melihat dan menguji operasi. Di konsol pengujian portal, secara default, API dipanggil dengan menggunakan kunci dari langganan all-access bawaan. Anda juga dapat menguji panggilan API dengan menggunakan kunci langganan yang ditetapkan untuk produk.

  1. Dalam instans API Management Anda, pilih APIs>APIs>Swagger Petstore.

  2. Pilih tab Uji , lalu pilih Temukan Hewan Peliharaan menurut status. Halaman memperlihatkan parameter Kueri status. Pilih salah satu nilai yang tersedia, seperti tertunda. Anda juga bisa menambahkan parameter dan header kueri di sini.

    Di bagian permintaan HTTP, header Ocp-Apim-Subscription-Key diisi secara otomatis untuk Anda, yang dapat Anda lihat jika Anda memilih simbol "mata".

  3. Pilih Kirim.

    Screenshot pengujian API di Azure portal.

    Backend memberikan respons dengan 200 OK dan beberapa data.

Cara API Management merutekan permintaan

API Management bertindak sebagai gateway antara klien API dan layanan backend Anda. Saat klien membuat permintaan ke API yang dikelola oleh API Management, perutean mengikuti pola ini:

URL permintaan klien:
[API Management gateway URL] + [API URL suffix] + [Operation endpoint]

API Management meneruskan permintaan ke layanan backend menggunakan pola ini:

URL layanan backend:
[Web service URL] + [Operation endpoint]

Nota

Titik akhir Operation harus identik dalam definisi API pada Manajemen API dan layanan backend agar routing berfungsi dengan benar. Titik akhir operasi yang tidak cocok mengakibatkan 404 atau kesalahan perutean lainnya.

Tabel berikut menjelaskan setiap parameter perutean dalam konteks contoh API Petstore yang digunakan dalam tutorial ini:

Pengaturan Deskripsi Contoh (Petstore API)
API Management gateway URL URL dasar instans API Management Anda https://apim-hello-world.azure-api.net
Sufiks URL API Akhiran unik yang mengidentifikasi API Anda di API Management (dikonfigurasi selama pembuatan API) petstore
URL layanan web URL dasar layanan backend Anda berasal dari spesifikasi OpenAPI https://petstore3.swagger.io/api/v3
Titik akhir operasi Jalur ke titik akhir operasi tertentu (berasal dari spesifikasi API Anda) /pet/findByStatus

Contoh: Menemukan hewan peliharaan berdasarkan status

Menggunakan API Petstore yang diimpor dalam tutorial ini:

  • Klien memanggil API Management:
    https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

    • URL gerbang Manajemen API: https://apim-hello-world.azure-api.net
    • Akhiran URL API: petstore
    • Titik akhir operasi: /pet/findByStatus

  • rute API Management ke backend:
    https://petstore3.swagger.io/api/v3/pet/findByStatus?status=pending

    • URL layanan web: https://petstore3.swagger.io/api/v3
    • Titik akhir operasi: /pet/findByStatus (sama seperti dalam definisi API Management)

Langkah selanjutnya

Lanjutkan ke tutorial berikutnya untuk mempelajari cara membuat dan menerbitkan produk:

Membuat dan menerbitkan produk

  • Last updated on