GitHub Actions kullanarak API'leri API merkezinize kaydetme

Bu makalede, bir API belirtimi dosyası GitHub deposuna eklendiğinde api'yi kuruluşunuzun API merkezine kaydetmek için temel bir GitHub Actions iş akışının nasıl ayarlanacağı gösterilmektedir.

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ışı kullanılarak API merkezinizdeki API kaydının nasıl otomatikleştirilebilir olduğu gösterilmektedir.

1. Deponuzda API tanım dosyası ekleyen bir çekme isteği birleştirildiğinde tetiklenen 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 dalla birleştirmek için bir çekme isteği oluşturun.
5. Çekme isteğini birleştirin.
6. Birleştirme, API'yi API merkezinize kaydeden bir GitHub Actions iş akışını tetikler.

Önkoşullar

• Azure aboneliğinizde bir API merkezi. Henüz oluşturmadıysanız bkz . Hızlı Başlangıç: API merkezinizi oluşturma.

• Microsoft Entra Id kiracısında 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'de Bash için hızlı başlangıç.

    

  • 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 ile oturum açma.

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

    • 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ı Için Azure CLI uzantısı gerekir apic-extension . Komutları kullanmadıysanız az apic , ilk az apic komutunuzu çalıştırdığınızda uzantı dinamik olarak yüklenebilir veya uzantıyı el ile yükleyebilirsiniz. Azure CLI uzantıları hakkında daha fazla bilgi edinin.

  içindeki en son değişiklikler ve güncelleştirmeler için sürüm notlarınıapic-extensioninceleyin. Bazı özellikler, uzantının önizlemesini veya belirli bir sürümünü gerektirebilir.

  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.

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 dizi olarak ekleyin.
• API tanım dosyası ekleyen bir çekme isteği birleştirildiğinde tetiklenen bir GitHub Actions 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 sorumlusu gizli dizisi ayarlama

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

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. Hizmet sorumlusu daha sonra API center için Azure API Center Hizmeti Katkıda Bulunanı rolüyle oluşturulur.

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

Aşağıdakine 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 gizli dizisi olarak ekleme

1. GitHub'da deponuza göz atın. Ayarlar'ı seçin.

2. Güvenlik bölümünde Gizli Diziler>ve değişkenler Eylemler'i seçin

3. Yeni depo gizli dizisi'ni seçin.

4. Azure CLI komutundaki JSON çıkışının tamamını gizli dizinin değer alanına yapıştırın. Gizli diziyi AZURE_CREDENTIALSolarak adlandırın. Add secret (Gizli dizi ekle) öğesini seçin.

   Gizli dizi, Depo gizli dizileri altında listelenir.

   

GitHub iş akışı dosyasını daha sonra yapılandırdığınızda, Azure/oturum açma eyleminin girişi creds için gizli diziyi 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ıyla temsil edilir. Bu tanım, iş akışını oluşturan çeşitli adımları ve parametreleri içerir. Daha fazla bilgi edinin

Aşağıda, bu örnek için kullanabileceğiniz veya değiştirebileceğiniz temel bir iş akışı dosyası verilmiştir.

Bu örnekte:

• Yola JSON tanımı ekleyen bir çekme isteği ana dalda APIs kapatıldığında iş akışı tetikleniyor.
• Tanımın konumu, çekme isteğinden, varsayılan GitHub belirteci ile kimliği doğrulanmış bir GitHub betiği kullanılarak 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:

1. Dosyayı kopyalayın ve gibi register-api.ymlbir adla kaydedin.
2. API tanım dosyasını ekleyeceğiniz 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ınız ve RESOURCE_GROUP kaynak grubu adınız için Eylemler değişkenleriniSERVICE_NAME ve deponuzda ayarlayın.

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 belgelerine bakın.

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

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

3. Değişiklikleri işleyin ve çalışma dalına gönderin.

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

5. Gözden geçirdikten sonra çekme 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 gidin.
2. Soldaki menüde, Varlıklar'ın altında API'ler'i seçin.
3. Yeni kaydedilen API'nin API'ler listesinde göründüğünü doğrulayın.

Yeni API sürümü ekleme

API merkezinizdeki mevcut bir API'ye yeni bir sürüm eklemek için, önceki adımları izleyerek küçük bir değişiklik yapın:

1. Deponuzda aynı çalışma dalı olarak değiştirin veya yeni bir çalışma dalı oluşturun.
2. Yoldaki APIs depoya, var olan bir API'nin klasörüne yeni bir API tanım dosyası ekleyin. Örneğin, daha önce bir Cat Facts API tanımı eklediyseniz gibi APIs/catfacts-api/07-22-2024.jsonyeni bir sürüm ekleyin.
3. Değişiklikleri işleyin ve çalışma dalına gönderin.
4. Çalışma dalını ana dalla birleştirmek için bir çekme isteği oluşturun.
5. Gözden geçirdikten sonra çekme 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 yeni sürümün kayıtlı olduğunu 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ı , teamve cost centergibi approverözellikler içeriyorsa meta veri JSON dosyası aşağıdaki gibi görünebilir:

   {
     "approver": "diego@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'ta gizli dizileri kullanma
• Depo için yapılandırma değişkenleri oluşturma