Aracılığıyla paylaş

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

  • Makale

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

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.

Ö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 yüksek kullanılabilirlik ve performans için isteğe bağlı olarak CDN gibi bir çözüm tarafından öne alınan bir barındırma platformuna dağıtım
  • Barındırma altyapısını koruma ve yönetme
  • Kod tabanını yükseltirken kod çakışmalarını çözmenizi gerektirebilecek güvenlik düzeltme ekleri de dahil olmak üzere el ile güncelleştirmeler

Not

Şirket içinde barındırılan portal, yönetilen geliştirici portalında kullanılabilen görünürlük ve erişim denetimlerini desteklemez.

Yönetilen portalda medya dosyalarını zaten yüklediyseniz veya değiştirdiyseniz, bu makalenin devamında yönetilen dosyalardan şirket içinde barındırılanlara taşıma 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 kopyalamanız, geliştirici portalının en son sürümüne geçmeniz ve npm paketlerini yüklemeniz gerekir.

  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 çatallı portalınızı güncel tutun. Yazılım Mühendisleri günlük geliştirme amacıyla bu deponun dalını kullanır master . 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

Geliştirici portalı, içeriği yönetmek için API Management REST API'sini gerektirir.

config.design.json dosyası

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

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

Dosyayı yapılandırın:

  1. managementApiUrl değerinde değerini API Management örneğinizin adıyla değiştirin<service-name>. Özel bir etki alanı yapılandırdıysanız, bunun yerine bu etki alanını kullanın (örneğin, https://management.contoso.com).

    {
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...

  2. API Management örneğine doğrudan REST API erişimini etkinleştirmek için el ile bir SAS belirteci oluşturun.

  3. Oluşturulan belirteci kopyalayın ve değer olarak yapıştırın managementApiAccessToken .

  4. backendUrl değerinde değerini API Management örneğinizin adıyla değiştirin<service-name>. Özel bir etki alanı yapılandırdıysanız, bunun yerine bu etki alanını kullanın (örneğin, https://portal.contoso.com).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

  5. 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.

  6. içinde integrationaltında, googleFontsisteğe bağlı olarak Web Yazı Tipleri Geliştirici API'sine erişim sağlayan bir Google API anahtarı olarak ayarlayın apiKey . Bu anahtar yalnızca geliştirici portalı düzenleyicisinin Stiller bölümüne Google yazı tipleri eklemek istiyorsanız gereklidir.

    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ı'nın altında Anahtarı kısıtla'yı seçin. Açılan listede Web Yazı Tipleri Geliştirici API'sini seçin.
    7. Kaydet'i seçin.

config.publish.json dosyası

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

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Dosyayı yapılandırın:

  1. Önceki yapılandırma dosyasındaki managementApiUrl ve managementApiAccessToken değerlerini kopyalayıp yapıştırın.

  2. 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.

config.runtime.json dosyası

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

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

Dosyayı yapılandırın:

  1. Önceki yapılandırma dosyasındaki managementApiUrl değeri kopyalayıp yapıştırın.

  2. backendUrl değerinde değerini API Management örneğinizin adıyla değiştirin<service-name>. Özel bir etki alanı yapılandırdıysanız, bunun yerine bu etki alanını kullanın (örneğin. https://portal.contoso.com).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

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 depolama hesabınıza gidin ve soldaki menüden Statik web sitesi'ni seçin.

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

  3. Dizin belgesi adı alanına index.html girin.

  4. Hata belgesi yolu alanına 404/index.html girin.

  5. Kaydet'i seçin.

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

Depolama hesabı için Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) ayarlarını yapılandırın:

  1. Azure portalında depolama hesabınıza gidin ve soldaki menüden CORS'yi seçin.

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

    Kural Değer
    İzin verilen çıkış noktaları *
    İzin verilen yöntemler Tüm HTTP fiillerini seçin.
    İzin verilen üst bilgiler *
    Kullanıma sunulan üst bilgiler *
    En fazla yaş 0

  3. Kaydet'i 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ç uç noktasına (portal yapılandırma dosyalarında backendUrl ayarlanır) dayanır:

CORS ayarları eklemek için:

  1. Azure portalında API Management örneğine gidin ve soldaki menüden Geliştirici portalı portalı>ayarları'nı seçin.
  2. Şirket içinde barındırılan portal yapılandırma sekmesinde bir veya daha fazla Kaynak etki alanı değeri ekleyin. Örneğin:
    • Şirket içinde barındırılan portalın barındırıldığı etki alanı, örneğin https://www.contoso.com
    • localhost veya gibi http://localhost:8080 yerel geliştirme için (varsa) https://localhost:8080
  3. Kaydet'i 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.

Şu komutu çalıştırın:

npm start

Kısa 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 yapılan tüm değişiklikler tarayıcı pencerenizin yeniden oluşturulmasını ve yenilenmesini tetikler.

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
  • İçerik yazma
  • 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: Yerel olarak yayımlama

Portal verileri, güçlü türemiş nesneler biçiminde oluşturulur. Aşağıdaki komut bunları statik dosyalara çevirir ve çıktıyı dizine ./dist/website yerleştirir:

npm run publish

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 kabuğu açın.

  2. Aşağıdaki Azure CLI komutunu çalıştırın.

    değerini depolama hesabınızın bağlantı dizesi ile değiştirin<account-connection-string>. Depolama hesabınızın Erişim anahtarları bölümünden alabilirsiniz.

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

7. Adım: Web sitenize gidin

Web siteniz artık Azure Depolama özelliklerinizde belirtilen ana bilgisayar adı altında (Statik web sitelerinde birincil uç nokta) canlı olarak bulunur.

8. Adım: 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 etmek için 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:

Not

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ştirildi

<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ştirildi

<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ştirildi

<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ştirildi

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ştirildi

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ştirildi

<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ştirildi

<!--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ştirildi

<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ştirildi

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

Yönetilenden şirket içinde barındırılan geliştirici portalına geçme

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. Eski 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 şirket içinde 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 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 genel bir şirket içinde barındırılan portal ayarlama 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. Öğretici: SAS kimlik bilgileri aracılığıyla Azure Depolama erişmek için Linux VM sistem tarafından atanan kimliği 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.

Sonraki adımlar

  • Kendi kendine barındırmaya yönelik alternatif yaklaşımlar hakkında bilgi edinin