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

Bu öğreticide, uygulama geliştirici portalını nasıl API Management açık bir şekilde anlattır. Kendi kendine barındırma, çalışma zamanında sayfaları dinamik olarak özelleştiren özel mantık ve pencere öğeleriyle geliştirici portalını genişletme esnekliği sağlar. Uygulama örneğiniz için farklı özelliklere sahip API Management portalları kendi kendine barındırabilirsiniz. Bir portalı kendi kendine barındırarak bakımcı olur ve yükseltmeleri sizin sorumluluğunda olur.

Aşağıdaki adımlarda, yerel geliştirme ortamınızı ayarlama, geliştirici portalında değişiklikleri gerçekleştirin ve bunları bir Azure depolama hesabına yayımlayın ve dağıtın.

Yönetilen portalda medya dosyalarını zaten karşıya yükledikten veya değiştirdikten sonra bu makalenin devamında Yönetilen dosyalardan kendi kendine barındırılan 'a taşıma makalesine bakın.

Kullanılabilirlik

Önemli

Bu özellik, API Management Premium, Standart, temel ve Geliştirici katmanlarında kullanılabilir.

Önkoşullar

Yerel bir geliştirme ortamı ayarlamak için şunların 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. Api-management-developer-portal GitHub:

    git clone https://github.com/Azure/api-management-developer-portal.git
    
  2. Yerel repo kopyanıza gidin:

    cd api-management-developer-portal
    
  3. Portalın en son sürümüne göz atabilirsiniz.

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

    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 forked portalını güncel bırakın. Yazılım Mühendisleri bu master deponun dallarını günlük geliştirme amacıyla kullanır. Yazılımın kararsız sürümlerine sahip.

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

Geliştirici portalı, API Management REST API için gerekli.

config.design.json dosyası

klasörüne src gidin ve dosyayı config.design.json açın.

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

Dosyayı yapılandırma:

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

    {
    ...
    "managementApiUrl": "https://contoso-api.management.azure-api.net"
    ...
    
  2. Doğrudan uygulama örneğinize doğrudan erişim sağlamak REST API SAS belirteci API Management oluşturun.

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

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

    {
    ...
    "backendUrl": "https://contoso-api.developer.azure-api.net"
    ...
    
  5. Geliştirici portalında CAPTCHA'yı etkinleştirmek için bkz. CAPTCHA'yı etkinleştirme.

config.publish.json dosyası

klasörüne src gidin ve dosyayı config.publish.json açın.

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

Dosyayı yapılandırma:

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

  2. Geliştirici portalında CAPTCHA'yı etkinleştirmek için bkz. CAPTCHA'yı etkinleştirme.

config.runtime.json dosyası

klasörüne src gidin ve dosyayı config.runtime.json açın.

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

Dosyayı yapılandırma:

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

  2. değerinde backendUrl yerine örnek <service-name> örneğinizin adını API Management. Özel bir etki alanı yapılandırdıysanız,bunun yerine 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ıza Statik web sitesi özelliğini yapılandırma:

  1. Depolama hesabı menüsünden depolama hesabınıza Azure portal ve sol menüden Statik web sitesi'yi seçin.

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

  3. Dizin belgesi adı alanına şu index.html.

  4. Hata belge yolu alanına 404/index.html.

  5. Kaydet’i seçin.

CORS ayarlarını yapılandırma

Çıkış Noktası Arası Kaynak Paylaşımı (CORS) ayarlarını yapılandırma:

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

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

    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 *
    Yaş üst sınırı 0
  3. Kaydet’i seçin.

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

Artık geliştirme modunda yerel bir portal örneği derleme ve çalıştırma. Geliştirme modunda, tüm iyileştirmeler kapalıdır ve kaynak eşlemeler açıktır.

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

npm start

Kısa bir süre sonra varsayılan tarayıcı, yerel geliştirici portalı örneğiniz ile otomatik olarak açılır. Varsayılan adres http://localhost:8080 değeridir, ancak zaten meşgulse 8080 bağlantı noktası değişebilir. Projenin kod temeli üzerinde yapılan tüm değişiklikler, tarayıcı pencerenizi yeniden oluşturma ve yenilemeyi 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ı özelleştirme
  • İçerik yazma
  • Web sitesinin yapısını düzenleme
  • Görünümünü stilize et

Bkz. Öğretici: Geliştirici portalına erişme ve portalını ö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üre sahip nesneler şeklindedir. Aşağıdaki komut bunları statik dosyalara çevirir ve çıktıyı dizinine ./dist/website ekler:

npm run publish

6. Adım: Upload bloba yükleme

Yerel olarak oluşturulan statik dosyaları bir bloba yüklemek için Azure CLI'sini kullanın ve ziyaretçinizin bu dosyalara vara olduğundan emin olun:

  1. Komut Windows, PowerShell veya başka bir komut kabuğu açın.

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

    yerine <account-connection-string> depolama hesabınıza bağlı bağlantı dizesini kullanın. Depolama hesabınıza erişim anahtarları bölümünden ulaşabilirsiniz.

    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 özelliklerinde belirtilen ana bilgisayar adı altında ( statik web sitelerindeki****birincil uç noktada ) canlı olarak bulunur.

8. Adım: API Management bildirim şablonlarını değiştirme

API Management bildirim şablonlarındaki geliştirici portalı URL 'sini kendi kendine barındırılan portalınızı işaret etmek üzere değiştirin. Bkz. Azure API Management 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ı https: / /Portal.contoso.com/ konumunda 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üncellendi

<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üncellendi

<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ıyı davet et

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

Özgün içerik

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

Güncellendi

<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 etkin bildirim şablonunda 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üncellendi

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üncellendi

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üncellendi

<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üncellendi

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

Parola değiştirme 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üncellendi

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

Tüm şablonlar

Altbilgide bağlantısı olan herhangi bir şablonda geliştirici portalı URL 'sini güncelleştirin:

Özgün içerik

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

Güncellendi

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

Yönetilen 'ten şirket içinde barındırılan geliştirici portalına taşıma

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

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 yaptığınız değişiklikleri korur. Portalın içeriğini önceden yedeklediğinizden emin olun. yedekleme betiğini, scripts API Management geliştirici portalının GitHub deposuklasöründe bulabilirsiniz.

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

İpucu

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

CAPTCHA 'yı etkinleştir

Şirket içinde barındırılan portalı ayarlarken, bu ayar aracılığıyla CAPTCHA ' yı devre dışı bırakmış olabilirsiniz useHipCaptcha . CAPTCHA ile iletişim, yalnızca yönetilen geliştirici portalı ana bilgisayar adı için çıkış noktaları arası kaynak paylaşımı (CORS) oluşmasını sağlayan bir uç nokta aracılığıyla gerçekleştirilir. Geliştirici portalınız şirket içinde barındırılıyorsa, farklı bir konak adı kullanır ve CAPTCHA, iletişime izin vermez.

JSON yapılandırma dosyalarını güncelleştirme

Kendi kendine barındırılan portalınızdaki CAPTCHA 'yı etkinleştirmek için:

  1. api.contoso.comAPI Management hizmetinizin Geliştirici Portalı uç noktasına özel bir etki alanı (örneğin,) atayın.

    Bu etki alanı, portalınızın yönetilen sürümü ve CAPTCHA uç noktası için geçerlidir. Adımlar için bkz. Azure API Management örneğiniz için özel etki alanı adı yapılandırma.

  2. srcKendi kendine barındırılan portalınız için Yerel ortamdaki klasöre gidin.

  3. Yapılandırma dosyalarını güncelleştirin json :

    Dosya Yeni değer Not
    config.design.json "backendUrl": "https://<custom-domain>" <custom-domain>İlk adımda ayarladığınız özel etki alanı ile değiştirin.
    "useHipCaptcha": true Değeri şu şekilde değiştirin true
    config.publish.json "backendUrl": "https://<custom-domain>" <custom-domain>İlk adımda ayarladığınız özel etki alanı ile değiştirin.
    "useHipCaptcha": true Değeri şu şekilde değiştirin true
    config.runtime.json "backendUrl": "https://<custom-domain>" <custom-domain>İlk adımda ayarladığınız özel etki alanı ile değiştirin.
  4. Portalı yayımlayın .

  5. yeni yayınlanan portalı Upload ve barındırın.

  6. Şirket içinde barındırılan portalı özel bir etki alanı aracılığıyla kullanıma sunun.

Portalın etki alanının ilk ve ikinci seviyelerinin ilk adımda ayarlanan etki alanı ile eşleşmesi gerekir. Örneğin, portal.contoso.com. Tam adımlar, tercih ettiğiniz barındırma platformunuza bağlıdır. bir azure depolama hesabı kullandıysanız yönergeler için özel bir etki alanını azure Blob Depolama uç noktası ile eşleme konusuna başvurabilirsiniz.

Sonraki adımlar