Mendaftarkan API di pusat API Anda menggunakan GitHub Actions

Artikel
12/23/2024

Artikel ini memperlihatkan cara menyiapkan alur kerja GitHub Actions dasar untuk mendaftarkan API di pusat API organisasi Anda saat file spesifikasi API ditambahkan ke repositori GitHub.

Menggunakan alur kerja GitHub Actions untuk mendaftarkan API di pusat API Anda menyediakan proses CI/CD yang konsisten dan dapat diulang untuk setiap API baru atau yang diperbarui. Alur kerja dapat diperluas untuk menyertakan langkah-langkah seperti menambahkan metadata ke pendaftaran API.

Diagram berikut menunjukkan bagaimana pendaftaran API di pusat API Anda dapat diotomatisasi menggunakan alur kerja GitHub Actions.

Siapkan alur kerja GitHub Actions di repositori Anda yang memicu saat permintaan pull yang menambahkan file definisi API digabungkan.
Buat cabang dari cabang utama di repositori GitHub Anda.
Tambahkan file definisi API, terapkan perubahan, dan dorong ke cabang baru.
Buat permintaan pull untuk menggabungkan cabang baru ke cabang utama.
Gabungkan permintaan pull.
Penggabungan memicu alur kerja GitHub Actions yang mendaftarkan API di pusat API Anda.

Prasyarat

Pusat API di langganan Azure Anda. Jika Anda belum membuatnya, lihat Mulai Cepat: Membuat pusat API Anda.
Izin untuk membuat perwakilan layanan di penyewa ID Microsoft Entra
Akun GitHub dan repositori GitHub tempat Anda dapat mengonfigurasi rahasia dan alur kerja GitHub Actions
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. Fitur tertentu mungkin memerlukan pratinjau atau versi ekstensi tertentu.

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.

Menyiapkan alur kerja GitHub Actions

Di bagian ini, Anda menyiapkan alur kerja GitHub Actions untuk skenario ini:

Buat perwakilan layanan yang akan digunakan untuk kredensial Azure dalam alur kerja.
Tambahkan kredensial sebagai rahasia di repositori GitHub Anda.
Konfigurasikan alur kerja GitHub Actions yang memicu saat permintaan pull yang menambahkan file definisi API digabungkan. File YAML alur kerja menyertakan langkah yang menggunakan Azure CLI untuk mendaftarkan API di pusat API Anda dari file definisi.

Menyiapkan rahasia perwakilan layanan

Dalam langkah-langkah berikut, buat perwakilan layanan ID Microsoft Entra, yang akan digunakan untuk menambahkan kredensial ke alur kerja untuk mengautentikasi dengan Azure.

Catatan

Mengonfigurasi perwakilan layanan ditampilkan untuk tujuan demonstrasi. Cara yang disarankan untuk mengautentikasi dengan Azure for GitHub Actions adalah dengan OpenID Connect, metode autentikasi yang menggunakan token berumur pendek. Menyiapkan OpenID Connect dengan GitHub Actions lebih kompleks tetapi menawarkan keamanan yang diperkuat. Pelajari lebih lanjut

Buat prinsipal layanan menggunakan perintah az ad sp create-for-rbac. Contoh berikut terlebih dahulu menggunakan perintah az apic show untuk mengambil ID sumber daya pusat API. Perwakilan layanan kemudian dibuat dengan peran Kontributor Layanan Azure API Center untuk pusat API.

Bash
PowerShell

#! /bin/bash
apiCenter=<api-center-name>
resourceGroup=<resource-group-name>
spName=<service-principal-name>

apicResourceId=$(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

# PowerShell syntax
$apiCenter = "<api-center-name>"
$resourceGroup = "<resource-group-name>"
$spName = "<service-principal-name>"

$apicResourceId = $(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

Salin output JSON, yang akan terlihat mirip dengan yang berikut ini:

{
  "clientId": "<GUID>",
  "clientSecret": "<GUID>",
  "subscriptionId": "<GUID>",
  "tenantId": "<GUID>",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  [...other endpoints...]
}

Menambahkan perwakilan layanan sebagai rahasia GitHub

Di GitHub, telusuri repositori Anda. Pilih pengaturan.
Di bawah Keamanan, pilih Tindakan Rahasia dan variabel>
Pilih Rahasia repositori baru.
Tempelkan seluruh output JSON dari perintah CLI Azure ke bidang nilai rahasia. Beri nama rahasia AZURE_CREDENTIALS. Pilih Tambahkan rahasia.

Rahasia ini tercantum di bawah Rahasia repositori.

Saat Mengonfigurasi file alur kerja GitHub nanti, Anda menggunakan rahasia untuk input credstindakan Azure/login . Contohnya:

- uses: azure/login@v1
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}

Menambahkan file alur kerja ke repositori GitHub Anda

Alur kerja GitHub Actions diwakili oleh file definisi YAML (.yml). Definisi ini berisi berbagai langkah dan parameter yang membentuk alur kerja. Pelajari lebih lanjut

Berikut ini adalah file alur kerja dasar untuk contoh ini yang dapat Anda gunakan atau ubah.

Dalam contoh ini:

Alur kerja dipicu ketika permintaan pull yang menambahkan definisi JSON di APIs jalur ditutup pada cabang utama.
Lokasi definisi diekstrak dari permintaan pull menggunakan skrip GitHub, yang diautentikasi dengan token GitHub default.
Kredensial Azure yang disimpan di repositori Anda digunakan untuk masuk ke Azure.
Perintah az apic register mendaftarkan API di pusat API yang ditentukan dalam variabel lingkungan.

Untuk mengonfigurasi file alur kerja:

Salin dan simpan file dengan nama seperti register-api.yml.
Konfirmasi atau perbarui nama folder repositori (APIs) tempat Anda akan menambahkan file definisi API.
Tambahkan file alur kerja ini di /.github/workflows/ jalur di repositori GitHub Anda.
Atur variabelSERVICE_NAME Tindakan dan RESOURCE_GROUP di repositori Anda untuk nama pusat API dan nama grup sumber daya Anda di Azure.

Tip

Dengan menggunakan ekstensi Visual Studio Code untuk Azure API Center, Anda dapat membuat file alur kerja awal dengan menjalankan perintah ekstensi. Di Palet Perintah, pilih Azure API Center: Daftarkan API. Pilih CI/CD>GitHub. Anda kemudian dapat mengubah atau memperluas file untuk skenario Anda.

name: Register API Definition to Azure API Center
on:
  pull_request:
    types: [ closed ]
    branches:
      - [ "main" ]
    paths:
      - "APIs/**/*.json"
permissions:
  contents: read
  pull-requests: read
jobs:
  register:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v2
      
      - name: Get specification file path in the PR
        id: get-file-location
        uses: actions/github-script@v5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const pull_number = context.payload.pull_request.number;
            const owner = context.repo.owner;
            const repo = context.repo.repo;
            const files = await github.rest.pulls.listFiles({
              owner,
              repo,
              pull_number
            });
            if (files.data.length === 1) {
              const filename = files.data[0].filename;
              core.exportVariable('API_FILE_LOCATION', filename);
              console.log(`API_FILE_LOCATION: ${{ env.API_FILE_LOCATION }}`);
            }
            else {
              console.log('The PR does not add exactly one specification file.');
            }

      - name: Azure login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Register to API Center
        uses: azure/CLI@v2
        with:
          azcliversion: latest
          inlineScript: |
            az apic api register -g ${{ vars.RESOURCE_GROUP }} -n ${{ vars.SERVICE_NAME }} --api-location ${{ env.API_FILE_LOCATION }}

Menambahkan file definisi API ke repositori

Uji alur kerja dengan menambahkan file definisi API ke repositori. Ikuti langkah-langkah tingkat tinggi ini, yang khas dari alur kerja pengembangan. Untuk detail tentang bekerja dengan cabang GitHub, lihat dokumentasi GitHub.

Buat cabang kerja baru dari cabang utama di repositori Anda.
Tambahkan file definisi API ke repositori di APIs jalur . Contohnya,APIs/catfacts-api/07-15-2024.json.
Terapkan perubahan dan dorong ke cabang kerja.
Buat permintaan pull untuk menggabungkan cabang kerja ke cabang utama.
Setelah ditinjau, gabungkan permintaan pull. Penggabungan memicu alur kerja GitHub Actions yang mendaftarkan API di pusat API Anda.

Memverifikasi pendaftaran API

Verifikasi bahwa API terdaftar di pusat API Anda.

Di portal Azure, navigasikan ke pusat API Anda.
Di menu sebelah kiri, di bawah Aset, pilih API.
Verifikasi bahwa API yang baru terdaftar muncul dalam daftar API.

Cuplikan layar API yang terdaftar di API Center setelah alur kerja.

Menambahkan versi API baru

Untuk menambahkan versi baru ke API yang ada di pusat API Anda, ikuti langkah-langkah sebelumnya, dengan sedikit modifikasi:

Ubah ke cabang kerja yang sama di repositori Anda, atau buat cabang kerja baru.
Tambahkan file definisi API baru ke repositori di APIs jalur, di folder untuk API yang ada. Misalnya, jika sebelumnya Anda menambahkan definisi CAT Facts API, tambahkan versi baru seperti APIs/catfacts-api/07-22-2024.json.
Terapkan perubahan dan dorong ke cabang kerja.
Buat permintaan pull untuk menggabungkan cabang kerja ke cabang utama.
Setelah ditinjau, gabungkan permintaan pull. Penggabungan memicu alur kerja GitHub Actions yang mendaftarkan versi API baru di pusat API Anda.
Di portal Azure, navigasikan ke pusat API Anda dan konfirmasikan bahwa versi baru terdaftar.

Memperluas skenario

Anda dapat memperluas alur kerja GitHub Actions untuk menyertakan langkah-langkah lain, seperti menambahkan metadata untuk pendaftaran API. Contohnya:

Dengan menggunakan skema metadata di pusat API Anda, buat file JSON metadata untuk menerapkan nilai metadata ke pendaftaran API Anda.

Misalnya, jika skema metadata menyertakan properti seperti approver, , teamdan cost center, file JSON metadata mungkin terlihat seperti ini:
```
{
  "approver": "diego@contoso.com",
  "team": "Store API dev team",
  "costCenter": "12345"  
}
```
Unggah file JSON metadata di folder untuk setiap API di repositori.

Tambahkan langkah alur kerja untuk menerapkan metadata ke pendaftaran API menggunakan perintah az apic api update . Dalam contoh berikut, ID API dan file metadata diteruskan dalam variabel lingkungan, yang akan diatur di tempat lain dalam file alur kerja.

[...]
- name: Apply metadata to API in API Center
    uses: azure/CLI@v2
    with:
      azcliversion: latest
      inlineScript: |
        az apic api update -g ${{ vars.RESOURCE_GROUP }} -n ${{ vars.SERVICE_NAME }} --api-id {{ env.API_ID }} --custom-properties {{ env.METADATA_FILE }}

Bagikan melalui

Mendaftarkan API di pusat API Anda menggunakan GitHub Actions

Prasyarat

Menyiapkan alur kerja GitHub Actions

Menyiapkan rahasia perwakilan layanan

Menambahkan perwakilan layanan sebagai rahasia GitHub

Menambahkan file alur kerja ke repositori GitHub Anda

Menambahkan file definisi API ke repositori

Memverifikasi pendaftaran API

Menambahkan versi API baru

Memperluas skenario

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Mendaftarkan API di pusat API Anda menggunakan GitHub Actions

Prasyarat

Menyiapkan alur kerja GitHub Actions

Menyiapkan rahasia perwakilan layanan

Menambahkan perwakilan layanan sebagai rahasia GitHub

Menambahkan file alur kerja ke repositori GitHub Anda

Menambahkan file definisi API ke repositori

Memverifikasi pendaftaran API

Menambahkan versi API baru

Memperluas skenario

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: