Aracılığıyla paylaş

API Management geliştirici portalını kendi kendine barındırma

ŞUNLAR IÇIN GEÇERLIDIR: Geliştirici | Temel | Temel v2 | Standart | Standart v2 | Premium | Premium v2

Bu öğreticide API Management geliştirici portalının nasıl kendi kendine barındırıldığı açıklanır. Kendi kendine barındırma, geliştirici portalının işlevselliğini genişletmek için çeşitli seçeneklerden biridir. Örneğin, API Management örneğiniz için farklı özelliklere sahip birden çok portalı kendi kendine barındırabilirsiniz. Bir portalı kendi kendine barındırdığınızda, portalın bakımcısı olursunuz ve yükseltmelerinden siz sorumlu olursunuz. Geliştirici portalı, içeriği yönetmek için API Management REST API'sini gerektirir.

Önemli

Geliştirici portalını yalnızca geliştirici portalının kod tabanının çekirdeğini değiştirmeniz gerektiğinde kendi kendine barındırmayı göz önünde bulundurun. Bu seçenek, aşağıdakiler dahil olmak üzere gelişmiş yapılandırma gerektirir:

  • Daha fazla kullanılabilirlik ve performans için, isteğe bağlı olarak İçerik Dağıtım Ağı (CDN) gibi bir çözüm ile desteklenen bir barındırma platformuna dağıtım.
  • Barındırma altyapısını koruma ve yönetme.
  • Güvenlik düzeltme ekleri de dahil olmak üzere, kod tabanını yükseltirken kod çakışmalarını çözmenizi gerektirebilecek el ile güncelleştirmeler.

Uyarı

Kendinden barındırmalı portal, yönetilen geliştirici portalında mevcut olan görünürlük ve erişim kontrollerini desteklemez.

Yönetilen portalda zaten medya dosyalarını yüklediyseniz veya değiştirdiyseniz, bu makalenin devamında yönetilenden kendi kendine barındırmaya geçiş bölümüne bakın.

Önkoşullar

Yerel bir geliştirme ortamı ayarlamak için şunları yapmanız gerekir:

1. Adım: Yerel ortamı ayarlama

Yerel ortamınızı ayarlamak için depoyu kopyalayın, geliştirici portalının en son sürümüne geçin ve npm paketlerini yükleyin.

  1. GitHub'dan api-management-developer-portal deposunu kopyalayın:

    git clone https://github.com/Azure/api-management-developer-portal.git

  2. Deponuzun yerel kopyasına gidin:

    cd api-management-developer-portal

  3. Portalın en son sürümüne göz atın.

    Aşağıdaki kodu çalıştırmadan önce, deponun Sürümler bölümünde geçerli sürüm etiketini denetleyin ve değeri en son sürüm etiketiyle değiştirin <current-release-tag> .

    git checkout <current-release-tag>

  4. Kullanılabilir npm paketlerini yükleyin:

    npm install

İpucu

Her zaman en son portal sürümünü kullanın ve forklanan portalınızı up-togüncel tutun. API Management geliştirme ekibi, günlük geliştirme amacıyla bu deponun dalını, master kullanır. Yazılımın kararsız sürümlerine sahiptir.

2. Adım: JSON dosyalarını, statik web sitesini ve CORS ayarlarını yapılandırma

config.design.json dosyası

Klasöre src gidin ve dosyayı açın config.design.json .

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

subscriptionId, resourceGroupNameve serviceNameiçine API Management örneğinizin abonelik, kaynak grubu ve hizmet adı değerlerini girin. I

config.design.json'de isteğe bağlı ayarlar

İsteğe bağlı olarak, dosyada config.design.json aşağıdaki ayarları yapılandırın:

  1. Geliştirici portalınızda CAPTCHA'yı etkinleştirmek istiyorsanız ayarını yapın "useHipCaptcha": true. Geliştirici portalı arka ucu için CORS ayarlarını yapılandırdığından emin olun.

    {
    ...
    "useHipCaptcha": true
    ...
}

  2. , altında, isteğe bağlı olarak Google API anahtarı olarak ayarlayabilir ve Web Yazı Tipleri Geliştirici API'sine erişim sağlayabilirsiniz.> Bu anahtar yalnızca geliştirici portalı düzenleyicisinin Stiller bölümüne Google yazı tipleri eklemek istiyorsanız gereklidir.

    {
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}

  3. Henüz bir anahtarınız yoksa, Google Cloud konsolunu kullanarak bir anahtar yapılandırabilirsiniz. Şu adımları izleyin:

    1. Google Cloud konsolunu açın.
    2. Web Yazı Tipleri Geliştirici API'sinin etkinleştirilip etkinleştirilmediğini denetleyin. Değilse etkinleştirin.
    3. Kimlik bilgileri>API anahtarı oluştur'u seçin.
    4. Açık iletişim kutusunda, oluşturulan anahtarı kopyalayın ve dosyaya değeri apiKey olarak yapıştırın config.design.json .
    5. Anahtar düzenleyicisini açmak için API anahtarını düzenle'yi seçin.
    6. Düzenleyicide, API kısıtlamaları altında Anahtarı Kısıtla seçin. Açılan listede Web Yazı Tipleri Geliştirici API'sini seçin.
    7. Kaydetseçeneğini seçin.

config.publish.json dosyası

Klasöre src gidin ve dosyayı açın config.publish.json .

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Önceki yapılandırma dosyasındaki subscriptionId, resourceGroupNameve serviceName değerlerini kopyalayıp yapıştırın.

config.runtime.json dosyası

Klasöre src gidin ve dosyayı açın config.runtime.json .

{
    "environment": "runtime",
    "backendUrl": "https://< service name >.developer.azure-api.net"
}

yerine < service name > önceki yapılandırma dosyalarında kullanılan API Management örneğinizin adını yazın.

Statik web sitesini yapılandırma

Dizine ve hata sayfalarına yollar sağlayarak depolama hesabınızdaki Statik web sitesi özelliğini yapılandırın:

  1. Azure portalında Azure portalında depolama hesabınıza gidin.

  2. Kenar çubuğu menüsünde Veri yönetimi>Statik web sitesi'ni seçin.

  3. Statik web sitesi sayfasında Etkin'i seçin.

  4. Dizin belgesi adı alanına index.htmlgirin.

  5. Hata belgesi yolu alanına 404/index.htmlgirin.

  6. Kaydetseçeneğini seçin.

Birincil uç nokta URL'sini not alın. Bunu daha sonra kendi sunucunuzda barındırılan portalınıza erişebilecek şekilde yapılandıracaksınız.

Depolama hesabı için CORS ayarlarını yapılandırma

Depolama hesabının çıkış noktaları arası kaynak paylaşımı (CORS) ayarlarını yapılandırmak için:

  1. Azure portalda depolama hesabınıza gidin.

  2. Kenar çubuğu menüsünde, Ayarlar'ın altında Kaynak paylaşımı (CORS) öğesini seçin.

  3. Blob hizmeti sekmesinde aşağıdaki kuralları yapılandırın:

    Kural Değer
    İzin verilen kaynaklar *
    İzin verilen yöntemler Tüm HTTP fiillerini seçin.
    İzin verilen başlıklar *
    Açığa çıkarılmış üst bilgiler *
    En fazla yaş 0

  4. Kaydetseçeneğini seçin.

Geliştirici portalı arka ucu için CORS ayarlarını yapılandırma

Şirket içinde barındırılan geliştirici portalınızdan kaynaklanan isteklere izin vermek için geliştirici portalı arka ucu için CORS ayarlarını yapılandırın. Şirket içinde barındırılan geliştirici portalı, aşağıdakiler gibi çeşitli özellikleri etkinleştirmek için geliştirici portalının arka uç uç noktasına (portal backendUrl dosyasında ayarlanırconfig.runtime.json) dayanır:

CORS ayarları eklemek için:

  1. Azure portalında API Management örneğine gidin.
  2. Kenar çubuğu menüsünde Geliştirici portalı>Ayarları'nı seçin.
  3. Kendi kendine barındırılan portal yapılandırma sekmesinde bir veya daha fazla Origin etki alanı değeri ekleyin. Örneğin:
    • Kendi kendine barındırılan portalın barındırıldığı etki alanı, örneğin https://contoso.developer.azure-api.net
    • localhost yerel geliştirme için (varsa), http://localhost:8080 veya https://localhost:8080 gibi
  4. Kaydetseçeneğini seçin.

3. Adım: Portalı çalıştırma

Artık geliştirme modunda yerel bir portal örneği derleyebilir ve çalıştırabilirsiniz. Geliştirme modunda tüm iyileştirmeler kapatılır ve kaynak haritalar açılır.

  1. Aşağıdaki komutu çalıştırın:

    npm run start

  2. Tarayıcınız aracılığıyla kimlik doğrulaması yapmanız istenir. Devam etmek için Microsoft kimlik bilgilerinizi seçin.

  3. Bir süre sonra varsayılan tarayıcı otomatik olarak yerel geliştirici portalı örneğinizle birlikte açılır. Varsayılan adres şeklindedir http://localhost:8080, ancak bağlantı noktası zaten meşgulse 8080 değişebilir. Projenin kod tabanında değişiklik yaptığınızda, yeniden derleme tetiklenir ve tarayıcı pencereniz yenilenir.

4. Adım: Görsel düzenleyici aracılığıyla düzenleme

Bu görevleri gerçekleştirmek için görsel düzenleyiciyi kullanın:

  • Portalınızı özelleştirme
  • Yazar içeriği
  • Web sitesinin yapısını düzenleme
  • Görünümünü stilize edin

Bkz. Öğretici: Geliştirici portalına erişme ve portalı özelleştirme. Yönetim kullanıcı arabiriminin temellerini kapsar ve varsayılan içerikte önerilen değişiklikleri listeler. Yerel ortamdaki tüm değişiklikleri kaydedin ve kapatmak için Ctrl+C tuşlarına basın.

5. Adım: Portalı yerel olarak yayımlama

  1. npm run publish'i çalıştırın. Tarayıcınız aracılığıyla kimlik doğrulaması yapmanız istenir. Devam etmek için Microsoft kimlik bilgilerinizi seçin.

  2. Bir süre sonra içerik klasörde yayımlanır dist/website .

6. Adım: Statik dosyaları bloba yükleme

Yerel olarak oluşturulan statik dosyaları bir bloba yüklemek ve ziyaretçilerinizin bunlara ulaşadığından emin olmak için Azure CLI'yi kullanın:

  1. Windows Komut İstemi, PowerShell veya başka bir komut satırı arayüzü açın.

  2. Aşağıdaki az storage blog upload-batch komutu çalıştırın. <connection-string> simgesini depolama hesabınız için bir bağlantı dizesiyle değiştirin. Bunu depolama hesabınızın Güvenlik + ağ>Erişim anahtarları bölümünden alabilirsiniz.

    az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"

7. Adım: Web sitenize gidin

Web siteniz artık Azure Depolama özelliklerinizde belirtilen ana bilgisayar adı altında yayındadır. Kenar çubuğu menüsünde Veri yönetimi>Statik web sitesine gidin. Konak adı Birincil uç noktanın değeridir.

Web sitesi düzenleyicisini barındırma

Web sitesi kodunda değişiklik yaparken, değiştirilen pencere öğelerinizin düzgün düzenlenmesini desteklemek için web sitesi düzenleyici kodunu güncelleştirmeniz gerekebilir. Bu durumda, portalı barındırmanın yanı sıra düzenleyici uygulamasını da barındırmak isteyebilirsiniz. Bunun için, API Management hizmetinize erişim sağlamak amacıyla bunu derlemeniz ve yapılandırmanız gerekir.

Bunun için kiracınızda bir Microsoft Entra ID uygulamasına ihtiyacınız vardır:

  1. Microsoft Entra Id kiracınıza bir uygulama kaydedin. Uygulama (istemci) kimliğini ve Dizin (kiracı) kimliğini not alın. Bunları sonraki bir adımda yapılandıracaksınız.
  2. Tasarımcının barındırıldığı web uygulamasının uç noktasına işaret etmek için bu uygulamada bir Web Yeniden Yönlendirme URI'si (yanıt URL'si) yapılandırın. Bu genellikle blob depolama tabanlı web sitesinin konumudur. Örnek: https://<your-storage-account-name>z13.web.core.windows.net/.
  3. Portalı işlem hatlarında (GitHub Actions) yayımlamak istiyorsanız, bu uygulama için bir istemci gizli anahtarı da oluşturun. Oluşturulan gizli değeri not alın ve güvenli bir konumda depolayın.

Ardından, web sitesi düzenleyicisini barındırmak için şu adımları izleyin:

  1. Dosyaya clientId ve tenantId alanları ekleyinconfig.design.json.

    {
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

  2. npm run build-designer Tasarımcı oluşturmak için komutunu çalıştırın.

  3. Aşağıdaki içeriğe sahip bir dosya /dist/designer içeren oluşturulan config.json klasöre gidin:

    {
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

  4. API Management hizmetinize Azure Resource Manager API'lerini kullanarak bağlanmak için gereken subscriptionId, resourceGroupName ve serviceName yapılandırmalarını onaylayın.

Portalı işlem hatlarında yayımlama (GitHub Actions)

Kendi kendine barındırılan portalı GitHub Actions gibi bir işlem hattında yayımlayabilirsiniz.

İşlem hattı, işlem hatlarını kullanarak yayımlamayı yürütmek için Entra ID uygulama kimlik bilgilerine de ihtiyaç duyar. Önceki adımlarda açıklanan Entra Id uygulamasının aynısını kullanabilirsiniz. tenantId, clientIdve özellikle clientSecret ilgili anahtar depolama alanında tutulmalıdır. Diğer ayrıntılar için bkz. GitHub Actions'ta gizli bilgileri kullanma .

GitHub Actions işlem hattı YAML örneği:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

API Management bildirim şablonlarını değiştirme

API Management bildirim şablonlarındaki geliştirici portalı URL'sini, şirket içinde barındırılan portalınıza işaret eden şekilde değiştirin. Bkz. Azure API Management'ta bildirimleri ve e-posta şablonlarını yapılandırma.

Özellikle, varsayılan şablonlarda aşağıdaki değişiklikleri gerçekleştirin:

Uyarı

Aşağıdaki Güncelleştirilmiş bölümlerdeki değerler portalı konumunda https://portal.contoso.com/barındırdığınızı varsayar.

E-posta değişikliği onayı

E-posta değişikliği onay bildirimi şablonunda geliştirici portalı URL'sini güncelleştirin:

Özgün içerik

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Güncelleştirilmiş

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Yeni geliştirici hesabı onayı

Yeni geliştirici hesabı onay bildirimi şablonunda geliştirici portalı URL'sini güncelleştirin:

Özgün içerik

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Güncelleştirilmiş

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Kullanıcı davet etme

Kullanıcı bildirimini davet et şablonunda geliştirici portalı URL'sini güncelleştirin:

Özgün içerik

<a href="$ConfirmUrl">$ConfirmUrl</a>

Güncelleştirilmiş

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Yeni abonelik etkinleştirildi

Yeni abonelik etkinleştirilmiş bildirim şablonundaki geliştirici portalı URL'sini güncelleştirin:

Özgün içerik

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Güncelleştirilmiş

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Özgün içerik

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Güncelleştirilmiş

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Özgün içerik

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Güncelleştirilmiş

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Özgün içerik

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

Güncelleştirilmiş

<!--Remove the entire block of HTML code above.-->

Parola değişikliği onayı

Parola değiştirme onayı bildirim şablonunda geliştirici portalı URL'sini güncelleştirin:

Özgün içerik

<a href="$DevPortalUrl">$DevPortalUrl</a>

Güncelleştirilmiş

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Tüm şablonlar

Alt bilgide bağlantısı olan tüm şablonlarda geliştirici portalı URL'sini güncelleştirin:

Özgün içerik

<a href="$DevPortalUrl">$DevPortalUrl</a>

Güncelleştirilmiş

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

kendi kendine barındırılan geliştirici portalına geçiş yapma

Zaman içinde iş gereksinimleriniz değişebilir. API Management geliştirici portalının yönetilen sürümünün artık gereksinimlerinizi karşılamadığı bir duruma gelebilirsiniz. Örneğin, yeni bir gereksinim sizi üçüncü taraf veri sağlayıcısıyla tümleşen özel bir pencere öğesi oluşturmaya zorlayabilir. Yönetilen sürümden farklı olarak portalın şirket içinde barındırılan sürümü size tam esneklik ve genişletilebilirlik sunar.

Geçiş işlemi

Yönetilen sürümden, aynı API Management hizmet örneği içinde kendi tarafından barındırılan bir sürüme geçiş yapabilirsiniz. İşlem, portalın yönetilen sürümünde gerçekleştirdiğiniz değişiklikleri korur. Portalın içeriğini önceden yedeklediğinizden emin olun. Yedekleme betiğini scripts.v3 API Management geliştirici portalı GitHub deposunun klasöründe bulabilirsiniz.

Dönüştürme işlemi, bu makaledeki önceki adımlarda gösterildiği gibi öz barındırmalı bir portal oluşturma işlemiyle neredeyse aynıdır. Yapılandırma adımında bir özel durum vardır. Dosyadaki config.design.json depolama hesabının, portalın yönetilen sürümünün depolama hesabıyla aynı olması gerekir. SAS URL'sini alma yönergeleri için bkz Kılavuz: SAS kimlik bilgileri aracılığıyla Azure Depolama'ya erişmek için Linux VM sistem tarafından atanan kimlik kullanma.

İpucu

Dosyada config.publish.json ayrı bir depolama hesabı kullanmanızı öneririz. Bu yaklaşım size daha fazla denetim sağlar ve portalınızın barındırma hizmetinin yönetimini basitleştirir.

İlgili içerik

  • Last updated on