Mengimpor API ke pusat API Anda dari Azure API Management

Artikel ini memperlihatkan cara mengimpor (menambahkan) API dari instans Azure API Management ke pusat API Anda menggunakan Azure CLI. Menambahkan API dari API Management ke inventarisasi API Anda membantu membuatnya dapat ditemukan dan dapat diakses oleh pengembang, manajer program API, dan pemangku kepentingan lainnya di organisasi Anda.

Artikel ini memperlihatkan dua opsi untuk menggunakan Azure CLI untuk menambahkan API ke pusat API Anda dari API Management:

• Opsi 1 - Ekspor definisi API dari instans API Management menggunakan perintah az apim api export . Kemudian, impor definisi ke pusat API Anda.

  Kemungkinan cara untuk mengimpor definisi API yang diekspor dari API Management meliputi:

  • Jalankan az apic api register untuk mendaftarkan API baru di pusat API Anda.
  • Jalankan spesifikasi impor definisi api az apic untuk mengimpor definisi API ke API yang ada.

• Opsi 2 - Impor API langsung dari API Management ke pusat API Anda menggunakan perintah az apic import-from-apim .

Setelah mengimpor definisi API atau API dari API Management, Anda dapat menambahkan metadata dan dokumentasi di pusat API Anda untuk membantu pemangku kepentingan menemukan, memahami, dan menggunakan API.

Tip

Anda juga dapat menyiapkan sinkronisasi otomatis APIS dari API Management ke pusat API Anda. Untuk informasi selengkapnya, lihat Menautkan instans API Management untuk menyinkronkan API ke pusat API Anda.

Prasyarat

• Pusat API di langganan Azure Anda. Jika Anda belum membuatnya, lihat Mulai Cepat: Membuat pusat API Anda.

• Satu atau beberapa instans Azure API Management, dalam langganan yang sama atau berbeda. Saat Anda mengimpor API langsung dari API Management, instans API Management dan pusat API harus berada di direktori yang sama. Jika Anda belum membuatnya, lihat Membuat instans Azure API Management.

• Satu atau beberapa API yang dikelola dalam instans API Management yang ingin Anda tambahkan ke pusat API Anda.

• Untuk 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.

  Catatan

  az apic perintah memerlukan apic-extension ekstensi Azure CLI. Jika Anda belum menggunakan az apic perintah, ekstensi dapat diinstal secara dinamis saat Anda menjalankan perintah pertama az apic , atau Anda dapat menginstal ekstensi secara manual. Pelajari selengkapnya tentang ekstensi Azure CLI.

  Lihat catatan rilis untuk perubahan dan pembaruan terbaru di apic-extension.

  Catatan

  Contoh perintah Azure CLI dalam artikel ini dapat berjalan di PowerShell atau shell bash. Jika diperlukan karena sintaks variabel yang berbeda, contoh perintah terpisah disediakan untuk dua shell.

Opsi 1: Ekspor definisi API dari API Management dan impor ke pusat API Anda

Pertama, ekspor API dari instans API Management Anda ke definisi API menggunakan perintah az apim api export . Bergantung pada skenario Anda, Anda dapat mengekspor definisi API ke file lokal atau URL.

Mengekspor API ke file definisi API lokal

Contoh perintah berikut mengekspor API dengan pengidentifikasi my-api dalam instans API myAPIManagement . API diekspor dalam format OpenApiJson ke file definisi OpenAPI lokal di jalur yang Anda tentukan.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Mengekspor API ke URL

Dalam contoh berikut, ekspor apim az mengekspor API dengan pengidentifikasi my-api dalam format OpenApiJson ke URL di penyimpanan Azure. URL tersedia selama sekitar 5 menit. Di sini, nilai URL disimpan dalam variabel $link .

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Daftarkan API di pusat API Anda dari definisi API yang diekspor

Anda dapat mendaftarkan API baru di pusat API Anda dari definisi yang diekspor dengan menggunakan perintah az apic api register .

Contoh berikut mendaftarkan API di pusat API myAPICenter dari file definisi OpenAPI lokal bernama definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

Mengimpor definisi API ke API yang ada di pusat API Anda

Contoh berikut menggunakan perintah az apic api definition import-specification untuk mengimpor definisi API ke API yang ada di pusat API myAPICenter . Di sini, definisi API diimpor dari URL yang disimpan dalam variabel $link .

Contoh ini mengasumsikan Anda memiliki API bernama my-api dan API terkait versi v1-0-0 dan entitas definisi openapi di pusat API Anda. Jika tidak, lihat Menambahkan API ke pusat API Anda.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Opsi 2: Impor API langsung dari instans API Management Anda

Berikut ini adalah langkah-langkah untuk mengimpor API dari instans API Management Anda ke pusat API Anda menggunakan perintah az apic import-from-apim . Perintah ini berguna ketika Anda ingin mengimpor beberapa API dari API Management ke pusat API Anda, tetapi Anda juga dapat menggunakannya untuk mengimpor satu API.

Saat Anda menambahkan API dari instans API Management ke pusat API Anda menggunakan az apic import-from-apim, hal berikut ini terjadi secara otomatis:

• Setiap versi, definisi, dan informasi penyebaran API disalin ke pusat API Anda.
• API menerima nama API yang dihasilkan sistem di pusat API Anda. Ini mempertahankan nama tampilan (judul) dari API Management.
• Tahap Siklus Hidup API diatur ke Desain.
• Azure API Management ditambahkan sebagai lingkungan.

Menambahkan identitas terkelola di pusat API Anda

Untuk skenario ini, pusat API Anda menggunakan identitas terkelola untuk mengakses API di instans API Management Anda. Bergantung pada kebutuhan Anda, konfigurasikan identitas terkelola yang ditetapkan sistem atau satu atau beberapa identitas terkelola yang ditetapkan pengguna.

Contoh berikut menunjukkan cara mengonfigurasi identitas terkelola yang ditetapkan sistem dengan menggunakan portal Azure atau Azure CLI. Pada tingkat tinggi, langkah-langkah konfigurasi serupa untuk identitas terkelola yang ditetapkan pengguna.

Portal

1. Di portal, navigasikan ke pusat API Anda.
2. Di menu sebelah kiri, di bawah Keamanan, pilih Identitas terkelola.
3. Pilih Sistem yang ditetapkan, dan atur status ke Aktif.
4. Pilih Simpan.

Azure CLI

Atur identitas yang ditetapkan sistem di pusat API Anda menggunakan perintah az apic update berikut. Ganti nama pusat API dan grup sumber daya Anda:

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Menetapkan identitas terkelola peran Pembaca Layanan API Management

Untuk mengizinkan impor API, tetapkan identitas terkelola pusat API Anda peran API Management Service Reader dalam instans API Management Anda. Anda dapat menggunakan portal atau Azure CLI.

Portal

1. Di portal, navigasikan ke instans API Management Anda.
2. Di menu sebelah kiri, pilih Kontrol akses (IAM).
3. Pilih + Tambahkan penetapan peran.
4. Pada halaman Tambahkan penetapan peran, atur nilai sebagai berikut:
   1. Pada tab Peran - Pilih Pembaca Layanan API Management.
   2. Pada tab Anggota, di Tetapkan akses ke - Pilih Identitas> terkelola+ Pilih anggota.
   3. Pada halaman Pilih identitas terkelola - Pilih identitas terkelola yang ditetapkan sistem dari pusat API yang Anda tambahkan di bagian sebelumnya. Klik Pilih.
   4. Pilih Tinjau + tetapkan.

Azure CLI

1. Dapatkan ID utama identitas. Untuk identitas yang ditetapkan sistem, gunakan perintah az apic show .

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. Dapatkan ID sumber daya instans API Management Anda menggunakan perintah az apim show .

   #! /bin/bash
   apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. Tetapkan identitas terkelola peran Pembaca Layanan API Management dalam instans API Management Anda menggunakan perintah az role assignment create .

   #! /bin/bash
   scope="${apimID:1}"
   
   az role assignment create \
       --role "API Management Service Reader Role" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "API Management Service Reader Role" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

Mengimpor API dari API Management

Gunakan perintah az apic import-from-apim untuk mengimpor satu atau beberapa API dari instans API Management Anda ke pusat API Anda.

Catatan

• Perintah ini bergantung pada identitas terkelola yang dikonfigurasi di pusat API Anda yang memiliki izin baca ke instans API Management. Jika Anda belum menambahkan atau mengonfigurasi identitas terkelola, lihat Menambahkan identitas terkelola di pusat API Anda sebelumnya di artikel ini.

• Jika pusat API Anda memiliki beberapa identitas terkelola, perintah akan mencari identitas yang ditetapkan sistem terlebih dahulu. Jika tidak ada yang ditemukan, identitas pertama yang ditetapkan pengguna dalam daftar akan dipilih.

Mengimpor semua API dari instans API Management

Dalam perintah berikut, ganti nama pusat API Anda, grup sumber daya pusat API, instans API Management, dan grup sumber daya instans Anda. Gunakan * untuk menentukan semua API dari instans API Management.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'  

Catatan

Jika instans API Management Anda memiliki sejumlah besar API, impor ke pusat API Anda mungkin memakan waktu.

Mengimpor API tertentu dari instans API Management

Tentukan API untuk diimpor menggunakan namanya dari instans API Management.

Dalam perintah berikut, ganti nama pusat API Anda, grup sumber daya pusat API, instans API Management, dan grup sumber daya instans Anda. Berikan nama API seperti petstore-api menggunakan --apim-apis parameter .

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'    

Catatan

Tentukan nama API menggunakan nama sumber daya API dalam instans API Management, bukan nama tampilan. Contoh: petstore-api alih-alih Petstore API.

Setelah mengimpor API dari API Management, Anda dapat melihat dan mengelola API yang diimpor di pusat API Anda.

Konten terkait

• Referensi Azure CLI untuk Azure API Center
• Referensi Azure CLI untuk API Management
• Mengelola inventori API dengan perintah Azure CLI
• Menetapkan peran Azure ke identitas terkelola
• Dokumentasi Azure API Management