GitHub Actions'ı kullanarak API'leri API merkezinize kaydetme

Bu makalede, kuruluşunuzun API merkezine api kaydetmek için temel bir GitHub Actions iş akışının nasıl ayarlanacağı gösterilmektedir. Kayıt, GitHub deposuna bir API belirtim dosyası eklendiğinde gerçekleşir.

API'leri API merkezinize kaydetmek için GitHub Actions iş akışı kullanmak, her yeni veya güncelleştirilmiş API için tutarlı ve yinelenebilir bir CI/CD işlemi sağlar. İş akışı, API kaydına meta veri ekleme gibi adımları içerecek şekilde genişletilebilir.

Aşağıdaki diyagramda, GITHub Actions iş akışıyla API merkezinizdeki API kaydının nasıl otomatikleştirilebilir olduğu gösterilmektedir.

İşlem aşağıdaki adımları içerir:

1. Depo içerisine bir API tanım dosyası ekleyen bir pull request birleştiğinde tetiklenecek bir GitHub Actions iş akışı ayarlayın.
2. GitHub deponuzdaki ana daldan bir dal oluşturun.
3. Bir API tanım dosyası ekleyin, değişiklikleri işleyin ve yeni dala gönderin.
4. Yeni dalı ana dal ile birleştirmek için bir pull request oluşturun.
5. Çekme isteğini birleştirin.
6. Birleştirme, API'yi API merkezinize kaydeden bir GitHub Actions iş akışını tetikler.

Not

Bu makaledeki Azure CLI komut örnekleri PowerShell veya bash kabuğunda çalıştırılabilir. Farklı değişken söz dizimi nedeniyle gerektiğinde, iki kabuk için ayrı komut örnekleri sağlanır.

Önkoşullar

• Azure aboneliğinizde bir API merkezi. Hızlı Başlangıç: API merkezinizi oluşturma (Azure portalı) yordamını izleyerek bir API merkezi oluşturabilirsiniz.

• Microsoft Entra ID kiracısında bir hizmet sorumlusu oluşturma izinleri.

• Gizli dizileri ve GitHub Actions iş akışlarını yapılandırabileceğiniz bir GitHub hesabı ve GitHub deposu.

• Azure CLI için:

  • Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz. Azure Cloud Shell'i kullanmaya başlama.

    

  • CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yı yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz . Docker kapsayıcısında Azure CLI'yi çalıştırma.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Diğer oturum açma seçenekleri için bkz. Azure CLI kullanarak Azure'da kimlik doğrulaması.

    • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma ve yönetme.

    • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

  Not

  az apic komutları, apic-extension Azure CLI uzantısı gerektirir. uzantı, ilk az apic komutunuzu çalıştırdığınızda dinamik olarak yüklenebilir veya uzantıyı el ile yükleyebilirsiniz. Daha fazla bilgi için bkz . Azure CLI Uzantılarını Yönetme: Yükleme, Güncelleştirme ve Kaldırma.

  içindeki apic-extensionen son değişiklikler ve güncelleştirmeler için sürüm notlarını inceleyin. Bazı özellikler için bir önizleme veya uzantının belirli bir sürümü gerekebilir.

GitHub Actions iş akışı ayarlama

Bu bölümde, bu senaryo için GitHub Actions iş akışını ayarlarsınız:

• İş akışında Azure kimlik bilgileri için kullanılacak bir hizmet sorumlusu oluşturun.
• Kimlik bilgilerini GitHub deponuza gizli olarak ekleyin.
• GitHub Actions'da, bir API tanım dosyası ekleyen pull request birleştirildiğinde tetiklenen bir iş akışı yapılandırın. İş akışı YAML dosyası, API'yi tanım dosyasından API merkezinize kaydetmek için Azure CLI'yi kullanan bir adım içerir.

Hizmet ilkesi anahtarı oluşturma

Aşağıdaki adımlar, Azure'da kimlik doğrulaması yapmak üzere iş akışına kimlik bilgileri eklemek için kullanılan bir Microsoft Entra ID hizmet sorumlusu oluşturur.

Not

Bir hizmet ilkesi yapılandırması, gösterim amacıyla açıklanmıştır. GitHub Actions için Azure'da kimlik doğrulaması yapmak için önerilen yol, kısa süreli belirteçler kullanan bir kimlik doğrulama yöntemi olan OpenID Connect'tir. GitHub Actions ile OpenID Connect'i ayarlamak daha karmaşıktır ancak sağlamlaştırılmış güvenlik sunar. Daha fazla bilgi için bkz. GitHub Actions kullanarak Azure App Service'e dağıtma - OpenID Connect için dağıtım kimlik bilgileri oluşturma.

az ad sp create-for-rbac komutunu kullanarak bir hizmet sorumlusu oluşturun. Aşağıdaki örnek, API merkezinin kaynak kimliğini almak için önce az apic show komutunu kullanır. Azure API Merkezi Hizmet Katkı Sağlayıcısı rolüyle API merkezi için hizmet ana yetkilisi oluşturulur.

Bash

#! /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

# 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

Aşağıdaki örneğe benzer olması gereken JSON çıkışını kopyalayın:

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

Hizmet sorumlusunu GitHub sırrı olarak ekleyin.

Hizmet sorumlusunu aldıktan sonra GitHub gizli anahtarı olarak ekleyin.

1. GitHub'da deponuza göz atın ve üst menü çubuğundan Ayarlar'ı seçin.

2. Sol gezintide Güvenlik altında Sırlar ve değişkenler>Eylemler seçin

3. Yeni depo sırrı seçin.

4. Gizli Dizi alanına Azure CLI komutundan tüm JSON çıkışını yapıştırın. Ad alanına girin AZURE_CREDENTIALS. Gizli ekle seçeneğini seçin.

   Gizli, Depo gizlileri altında listelenir.

   

GitHub iş akışı dosyasını daha sonra yapılandırdığınızda, Azure/login eyleminin creds girişi için bu gizliyi kullanırsınız. Örneğin:

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

İş akışı dosyasını GitHub deponuza ekleme

GitHub Actions iş akışı bir YAML (.yml) tanım dosyasında belirtilir. Bu tanım, iş akışını oluşturan çeşitli adımları ve parametreleri içerir. Daha fazla bilgi için bkz. GitHub Actions için iş akışı söz dizimi.

Aşağıdaki örnek, kullanabileceğiniz veya değiştirebileceğiniz temel bir iş akışı dosyası sağlar.

• Ana daldaki APIs yolunda bir JSON tanımı ekleyen çekme isteği kapatıldığında, iş akışı tetiklenir.

• Tanımlamanın konumu, varsayılan GitHub belirteci ile doğrulanmış bir GitHub betiği kullanılarak pull request'ten ayıklanır.

• Deponuza kaydedilen Azure kimlik bilgileri, Azure'da oturum açmak için kullanılır.

• az apic register komutu, API'yi ortam değişkenlerinde belirtilen API merkezine kaydeder.

İş akışı dosyasını yapılandırmak için şu adımları izleyin:

1. Dosyayı kopyalayın ve gibi register-api.ymlbir adla kaydedin.

2. API tanım dosyasını eklemeyi planladığınız depo klasörünün (APIs) adını onaylayın veya güncelleştirin.

3. Bu iş akışı dosyasını /.github/workflows/ GitHub deponuzdaki yola ekleyin.

4. Azure'da API merkezi adı ve kaynak grubu adı için SERVICE_NAMERESOURCE_GROUP ve deponuzda ayarlayın.

İpucu

Azure API Center için Visual Studio Code uzantısını kullanarak bir uzantı komutu çalıştırarak başlangıç iş akışı dosyası oluşturabilirsiniz. Komut Paleti'ne (Ctrl+Shift+P) Azure API Center: API'yi kaydetme yazın ve CI/CD>GitHub'ı seçin. Daha sonra senaryonuz için dosyayı değiştirebilir veya genişletebilirsiniz.

Örnek iş akışı dosyası aşağıda verilmişti:

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 }}

Depoya API tanım dosyası ekleme

Depoya bir API tanım dosyası ekleyerek iş akışını test edin. Geliştirme iş akışına özgü bu üst düzey adımları izleyin. GitHub dallarıyla çalışma hakkında ayrıntılı bilgi için GitHub belgelerindeki İşbirliğine dayalı geliştirme modelleri hakkında bölümüne bakın.

1. Deponuzdaki ana daldan yeni bir çalışma dalı oluşturun.

2. API tanım dosyasını APIs yolundaki depoya ekleyin. Örneğin, APIs/catfacts-api/07-15-2024.json.

3. Değişiklikleri kaydedin ve çalışma dalına yükleyin.

4. Çalışma dalını ana dallaya birleştirmek için bir pull isteği oluşturun.

5. Gözden geçirdikten sonra pull isteğini birleştirin. Birleştirme, API'yi API merkezinize kaydeden GitHub Actions iş akışını tetikler.

   

API kaydını doğrulama

API'nin API merkezinize kaydedildiğini doğrulayın.

1. Azure portalında API merkezinize göz atın.

2. Sol gezinti bölmesinde Stok bölümünü genişletin ve Varlıklar'ı seçin.

3. Yeni kaydedilen API'nin listede göründüğünü doğrulayın.

Yeni API sürümü ekleme

Küçük bir değişiklikle aynı adımları izleyerek API merkezinizdeki mevcut bir API'ye yeni bir sürüm ekleyebilirsiniz.

1. Depodaki aynı çalışma dalına geçin veya yeni bir çalışma dalı oluşturun.

2. Var olan bir API'nin klasöründeki APIs yolunda bulunan depoya yeni bir API tanım dosyası ekleyin. Örneğin, daha önce Cat Facts API tanımı eklediyseniz, APIs/catfacts-api/07-22-2024.json gibi yeni bir sürüm ekleyin.

3. Değişiklikleri kaydedin ve çalışma dalına yükleyin.

4. Çalışma dalını ana dallaya birleştirmek için bir pull isteği oluşturun.

5. Gözden geçirdikten sonra pull isteğini birleştirin. Birleştirme, API merkezinize yeni API sürümünü kaydeden GitHub Actions iş akışını tetikler.

6. Azure portalında API merkezinize gidin ve API'nin yeni sürümünün kaydedildiğini onaylayın.

Senaryoyu genişletme

GitHub Actions iş akışını, API kaydı için meta veri ekleme gibi diğer adımları içerecek şekilde genişletebilirsiniz. Örneğin:

1. API merkezinizdeki meta veri şemasını kullanarak, API kaydınıza meta veri değerleri uygulamak için bir meta veri JSON dosyası oluşturun.

   Örneğin, meta veri şeması , approverve teamgibi cost centerözellikler içeriyorsa meta veri JSON dosyası aşağıdaki gibi görünebilir:

   {
     "approver": "admin-user@contoso.com",
     "team": "Store API dev team",
     "costCenter": "12345"  
   }
   

2. Depodaki her API için klasörüne bir meta veri JSON dosyası yükleyin.

3. az apic api update komutunu kullanarak meta verileri API kaydına uygulamak için bir iş akışı adımı ekleyin. Aşağıdaki örnekte API kimliği ve meta veri dosyası, iş akışı dosyasının başka bir yerinde ayarlanacak ortam değişkenlerine geçirilir.

   [...]
   - 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 }}
   

İlgili içerik

• GitHub Actions'taki Gizliler
• GitHub Actions için iş akışı sözdizimi