Cara menyimpan dan mengonfigurasikan konfigurasi layanan API Management menggunakan Git

  • Artikel

BERLAKU UNTUK: Pengembang | Dasar | Standar | Premium

Setiap instans layanan API Management mempertahankan database konfigurasi yang berisi informasi tentang konfigurasi dan metadata untuk instans layanan. Perubahan dapat dilakukan pada instans layanan dengan mengubah pengaturan di portal Azure, menggunakan alat Azure seperti Azure PowerShell atau Azure CLI, atau membuat panggilan REST API. Selain metode ini, Anda dapat mengelola konfigurasi instans layanan menggunakan Git, mengaktifkan skenario seperti:

  • Penerapan versi konfigurasi - Unduh dan simpan berbagai versi konfigurasi layanan Anda
  • Perubahan konfigurasi massal - Buat perubahan pada beberapa bagian konfigurasi layanan Anda di repositori lokal Anda dan integrasikan kembali perubahan tersebut ke server dengan satu operasi
  • Toolchain dan alur kerja Git yang familier - Gunakan perkakas dan alur kerja Git yang sudah Anda kenal

Diagram berikut menunjukkan ikhtisar berbagai cara untuk mengonfigurasi instans layanan API Management Anda.

Diagram yang membandingkan cara mengonfigurasi Azure API Management.

Saat Anda membuat perubahan pada layanan menggunakan portal Azure, alat Azure seperti Azure PowerShell atau Azure CLI, atau REST API, Anda mengelola database konfigurasi layanan menggunakan titik akhir https://{name}.management.azure-api.net, seperti yang ditunjukkan di sisi kanan diagram. Sisi kiri diagram menggambarkan bagaimana Anda dapat mengelola konfigurasi layanan Anda menggunakan Git dan repositori Git untuk layanan Anda yang terletak di https://{name}.scm.azure-api.net.

Langkah-langkah berikut memberikan gambaran umum dari mengelola instans layanan API Management Anda menggunakan Git.

  1. Akses konfigurasi Git di layanan Anda
  2. Simpan database konfigurasi layanan Anda ke repositori Git Anda
  3. Kloning repo Git ke mesin lokal Anda
  4. Tarik repo terbaru ke mesin lokal Anda, dan terapkan serta dorong perubahan kembali ke repo Anda
  5. Sebarkan perubahan dari repo Anda ke database konfigurasi layanan Anda

Artikel ini menjelaskan cara mengaktifkan dan menggunakan Git untuk mengelola konfigurasi layanan Anda dan menyediakan referensi untuk file dan folder di repositori Git.

Penting

Fitur ini dirancang untuk bekerja dengan konfigurasi layanan API Management kecil hingga menengah, seperti yang diekspor berukuran kurang dari 10 MB, atau dengan kurang dari 10.000 entitas. Layanan dengan sejumlah besar entitas (produk, API, operasi, skema, dan sebagainya) mungkin mengalami kegagalan tak terduga saat memproses perintah Git. Jika Anda mengalami kegagalan tersebut, kurangi ukuran konfigurasi layanan Anda dan coba lagi. Hubungi Dukungan Azure jika Anda memerlukan bantuan.

Akses konfigurasi Git di layanan Anda

  1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.

  2. Di menu sebelah kiri, di bawah Penyebaran dan infrastruktur, pilih Repositori.

Screenshot yang menunjukkan cara mengakses konfigurasi Git untuk API Management.

Menyimpan konfigurasi layanan ke repositori Git

Perhatian

Rahasia apa pun yang tidak didefinisikan sebagai nilai bernama akan disimpan dalam repositori dan akan tetap ada dalam riwayatnya. Nilai bernama menyediakan tempat yang aman untuk mengelola nilai string konstan, termasuk rahasia, di semua konfigurasi dan kebijakan API, sehingga Anda tidak perlu menyimpannya secara langsung dalam pernyataan kebijakan. Untuk informasi selengkapnya,lihat Menggunakan nilai bernama dalam kebijakan Azure API Management.

Sebelum mengkloning repositori, simpan status konfigurasi layanan saat ini ke repositori.

  1. Pada halaman Repositori, pilih Simpan ke repositori.

  2. Buat perubahan yang diinginkan pada layar konfirmasi, seperti nama cabang untuk menyimpan konfigurasi, dan pilih Simpan.

Setelah beberapa saat konfigurasi disimpan, dan status konfigurasi repositori ditampilkan, termasuk tanggal dan waktu perubahan konfigurasi terakhir dan sinkronisasi terakhir antara konfigurasi layanan dan repositori.

Setelah konfigurasi disimpan ke repositori, konfigurasi dapat dikloning.

Untuk informasi tentang menyimpan konfigurasi layanan menggunakan REST API, lihat Konfigurasi penyewa - Simpan.

Mendapatkan informasi masuk akses

Untuk mengkloning repositori, selain URL ke repositori Anda, Anda memerlukan nama pengguna dan kata sandi.

  1. Pada halaman Repositori, pilih Akses informasi masuk di dekat bagian atas halaman.

  2. Perhatikan nama pengguna yang disediakan pada halaman Informasi masuk akses.

  3. Untuk membuat kata sandi, pertama-tama pastikan bahwa Kedaluwarsa diatur ke tanggal dan waktu kedaluwarsa yang diinginkan, lalu pilih Hasilkan.

Penting

Catat kata sandi ini. Setelah Anda meninggalkan halaman ini, kata sandi tidak akan ditampilkan lagi.

Kloning repositori ke mesin lokal Anda

Contoh berikut menggunakan alat Git Bash dari Git untuk Windows tetapi Anda dapat menggunakan alat Git apa pun yang Anda kenal.

Buka alat Git Anda di folder yang diinginkan dan jalankan perintah berikut untuk mengkloning repositori Git ke mesin lokal Anda, menggunakan perintah berikut:

git clone https://{name}.scm.azure-api.net/

Berikan nama pengguna dan kata sandi saat diminta.

Jika Anda menerima kesalahan, coba ubah perintah git clone Anda untuk menyertakan nama pengguna dan kata sandi, seperti yang diperlihatkan dalam contoh berikut.

git clone https://username:password@{name}.scm.azure-api.net/

Jika ini memberikan kesalahan, coba pengkodean URL bagian kata sandi perintah. Salah satu cara cepat untuk melakukan ini adalah dengan membuka Visual Studio, dan menerbitkan perintah berikut di Jendela Langsung. Untuk membuka Jendela Langsung, buka solusi atau proyek apa pun di Visual Studio (atau buat aplikasi konsol kosong baru), dan pilih Windows, Langsung dari menu Debug.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

Gunakan kata sandi yang dikodekan bersama dengan nama pengguna dan lokasi repositori Anda untuk membuat perintah git.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

Setelah kloning selesai, ubah direktori ke repositori Anda dengan menjalankan perintah seperti berikut.

cd {name}.scm.azure-api.net/

Jika Anda menyimpan konfigurasi ke cabang selain cabang default (master), periksa cabang:

git checkout <branch_name>

Setelah repositori dikloning, Anda dapat melihat dan mengerjakannya di sistem file lokal Anda. Untuk informasi selengkapnya, lihat Referensi struktur file dan folder repositori Git lokal.

Memperbarui repositori lokal Anda dengan konfigurasi instans layanan terbaru

Jika Anda membuat perubahan pada instans layanan API Management di portal Azure atau menggunakan alat Azure lainnya, Anda harus menyimpan perubahan ini ke repositori sebelum Anda dapat memperbarui repositori lokal dengan perubahan terbaru.

Untuk menyimpan perubahan menggunakan portal Azure, pilih Simpan ke repositori pada tab Repositori untuk instans API Management Anda.

Kemudian, untuk memperbarui repositori lokal Anda:

  1. Pastikan Anda berada di folder repositori lokal Anda. Jika Anda baru saja menyelesaikan perintah git clone, maka Anda harus mengubah direktori ke repositori Anda dengan menjalankan perintah seperti berikut.

    cd {name}.scm.azure-api.net/

  2. Di folder untuk repositori lokal Anda, jalankan perintah berikut.

    git pull

Dorong perubahan dari repositori lokal Anda ke repositori server

Untuk mendorong perubahan dari repositori lokal Anda ke repositori server, Anda harus menerapkan perubahan Anda dan kemudian mendorongnya ke repositori server. Untuk menerapkan perubahan Anda, buka alat perintah Git Anda, beralihlah ke direktori repositori lokal Anda, dan terbitkan perintah berikut.

git add --all
git commit -m "Description of your changes"

Untuk mendorong semua penerapan ke server, jalankan perintah berikut.

git push

Menyebarkan perubahan konfigurasi layanan ke instans layanan API Management

Setelah perubahan lokal Anda diterapkan dan didorong ke repositori server, Anda dapat menyebarkannya ke instans layanan API Management Anda.

  1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.

  2. Di menu sebelah kiri, di bawah Penyebaran dan infrastruktur, pilih Repositori>Sebarkan ke API Management.

  3. Pada halaman Sebarkan konfigurasi repositori, masukkan nama cabang yang berisi perubahan konfigurasi yang diinginkan, dan secara opsional pilih Hapus langganan produk yang dihapus. Pilih Simpan.

Untuk informasi tentang melakukan operasi ini menggunakan REST API, lihat Konfigurasi Penyewa - Sebarkan.

Referensi struktur file dan folder dari repositori Git lokal

File dan folder di repositori Git lokal berisi informasi konfigurasi tentang instans layanan.

Item Deskripsi
folder root manajemen api Berisi konfigurasi tingkat atas untuk instans layanan
folder apiReleas Berisi konfigurasi untuk rilis API dalam instans layanan
folder api Berisi konfigurasi untuk API dalam instans layanan
Folder apiVersionSets Berisi konfigurasi untuk set versi API dalam instans layanan
folder backend Berisi konfigurasi untuk sumber daya backend dalam instans layanan
folder grup Berisi konfigurasi untuk grup dalam instans layanan
folder kebijakan Berisi kebijakan dalam instans layanan
folder portalStyles Berisi konfigurasi untuk kustomisasi portal pengembang dalam instans layanan
folder portalTemplate Berisi konfigurasi untuk templat portal pengembang dalam instans layanan
folder produk Berisi konfigurasi untuk produk dalam instans layanan
folder templat Berisi konfigurasi untuk templat email dalam instans layanan

Setiap folder dapat berisi satu atau beberapa file, dan dalam beberapa kasus berisi satu atau beberapa folder, misalnya folder untuk setiap API, produk, atau grup. File dalam setiap folder adalah file khusus untuk jenis entitas yang dijelaskan oleh nama folder.

Jenis file Tujuan
json Informasi konfigurasi tentang entitas masing-masing
html Deskripsi tentang entitas, sering ditampilkan di portal pengembang
xml Pernyataan kebijakan
css Lembar gaya untuk kustomisasi portal pengembang

File-file ini dapat dibuat, dihapus, diedit, dan dikelola pada sistem file lokal Anda, dan perubahan tersebut disebarkan kembali ke instans layanan API Management Anda.

Catatan

Entitas berikut tidak terkandung dalam repositori Git dan tidak dapat dikonfigurasi menggunakan Git.

  • Pengguna
  • Langganan
  • Nilai bernama
  • Entitas portal pengembang selain gaya dan templat
  • Fragmen Kebijakan

Folder root manajemen api

Folder root api-management berisi file configuration.json yang berisi informasi tingkat atas tentang instans layanan dalam format berikut.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

Empat pengaturan pertama (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled, dan UserRegistrationTermsConsentRequired) memetakan ke pengaturan berikut pada tab Identitas di bagian Portal pengembang.

Pengaturan identitas Memetakan ke
RegistrationEnabled Adanya penyedia identitas Nama Pengguna dan kata sandi
UserRegistrationTerms Kotak teks Ketentuan penggunaan pada pendaftaran pengguna
UserRegistrationTermsEnabled Kotak centang Menunjukkan ketentuan penggunaan di halaman pendaftaran
UserRegistrationTermsConsentRequired Kotak centang Diperlukan persetujuan
RequireUserSigninEnabled Kotak centang Alihkan pengguna anonim ke halaman masuk

Empat pengaturan pertama (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled, dan DelegationValidationKey) memetakan ke pengaturan berikut pada tab Delegasi di bagian Portal pengembang.

Pengaturan delegasi Memetakan ke
DelegationEnabled Kotak centang Delegasikan masuk & daftar
DelegationUrl Kotak teks URL titik akhir delegasi
DelegatedSubscriptionEnabled Kotak centangDelegasikan langganan produk
DelegationValidationKey Kotak teks Delegasikan Kunci Validasi

Pengaturan terakhir, $ref-policy, memetakan ke file pernyataan kebijakan global untuk instans layanan.

folder apiReleas

Folder apiReleases berisi folder untuk setiap rilis API yang disebarkan ke API produksi, dan berisi item berikut.

  • apiReleases\<api release Id>\configuration.json - Konfigurasi untuk rilis, yang berisi informasi tentang tanggal rilis. Ini adalah informasi yang sama yang akan dikembalikan jika Anda memanggil operasi Dapatkan rilis tertentu.

folder api

Folder apis berisi folder untuk setiap API dalam instans layanan, yang berisi item berikut.

  • apis\<api name>\configuration.json - Konfigurasi untuk API, yang berisi informasi tentang URL layanan backend dan operasinya. Ini adalah informasi yang sama yang akan dikembalikan jika Anda memanggil operasi Dapatkan API tertentu.
  • apis\<api name>\api.description.html - Deskripsi API, sesuai dengan properti description dari entitas API di REST API.
  • apis\<api name>\operations\ - Folder yang berisi <operation name>.description.html file yang dipetakan ke operasi di API. Setiap file berisi deskripsi operasi tunggal di API, yang memetakan ke properti description dari entitas operasi di REST API.

Folder apiVersionSets

Folder apiVersionSets berisi folder untuk setiap set versi API yang dibuat untuk API, dan berisi item berikut.

  • apiVersionSets\<api version set Id>\configuration.json - Konfigurasi untuk set versi. Ini adalah informasi yang sama yang akan dikembalikan jika Anda memanggil operasi Dapatkan kumpulan versi tertentu.

folder grup

Folder groups berisi folder untuk setiap grup yang ditentukan dalam instans layanan.

  • groups\<group name>\configuration.json - Konfigurasi untuk grup. Ini adalah informasi yang sama yang akan dikembalikan jika Anda memanggil operasi Dapatkan grup tertentu.
  • groups\<group name>\description.html - Deskripsi grup, sesuai dengan properti description dari entitas grup.

folder kebijakan

Folder policies berisi pernyataan kebijakan untuk instans layanan Anda.

  • policies\global.xml - Kebijakan yang ditentukan pada cakupan global untuk instans layanan Anda.
  • policies\apis\<api name>\ - Jika Anda memiliki kebijakan yang ditentukan pada cakupan API, kebijakan tersebut akan dimuat dalam folder ini.
  • policies\apis\<api name>\<operation name>\ folder - Jika Anda memiliki kebijakan yang ditetapkan pada cakupan operasi, kebijakan tersebut terdapat dalam folder ini dalam file <operation name>.xml yang dipetakan ke pernyataan kebijakan untuk setiap operasi.
  • policies\products\ - Jika Anda memiliki kebijakan yang ditentukan pada cakupan produk, kebijakan tersebut terkandung dalam folder ini, yang berisi <product name>.xml file yang dipetakan ke pernyataan kebijakan untuk setiap produk.

folder portalStyles

Folder portalStyles berisi konfigurasi dan lembar gaya untuk kustomisasi portal pengembang yang tidak digunakan lagi dari instans layanan.

  • portalStyles\configuration.json - Berisi nama-nama lembar gaya yang digunakan oleh portal pengembang
  • portalStyles\<style name>.css - Setiap file <style name>.css berisi gaya untuk portal pengembang (Preview.css dan Production.css secara default).

folder portalTemplate

Folder portalTemplates berisi templat untuk menyesuaikan portal pengembang yang tidak digunakan lagi dari instans layanan.

  • portalTemplates\<template name>\configuration.json - Konfigurasi templat.
  • portalTemplates\<template name>\<page name>.html - Halaman HTML asli dan yang dimodifikasi dari templat.

folder produk

Folder products berisi folder untuk setiap produk yang ditentukan dalam instans layanan.

  • products\<product name>\configuration.json - Konfigurasi untuk produk. Ini adalah informasi yang sama yang akan dikembalikan jika Anda memanggil operasi Dapatkan produk tertentu.
  • products\<product name>\product.description.html - Deskripsi produk, sesuai dengan description properti entitas produk di REST API.

templat

Folder templates berisi konfigurasi untuk templat email dari instans layanan.

  • <template name>\configuration.json - Konfigurasi untuk templat email.
  • <template name>\body.html - Isi templat email.

Langkah berikutnya

Untuk informasi tentang cara lain untuk mengelola instans layanan Anda, lihat: