Samodzielne hostowanie portalu deweloperów usługi API Management

  • Artykuł

DOTYCZY: Developer | Podstawowa | Standardowa | Premium

W tym samouczku opisano sposób samodzielnego hostowania portalu deweloperów usługi API Management. Hosting własny to jedna z kilku opcji rozszerzania funkcjonalności portalu deweloperów. Na przykład możesz samodzielnie hostować wiele portali dla wystąpienia usługi API Management z różnymi funkcjami. Gdy samodzielnie hostujesz portal, stajesz się jego opiekunem i odpowiadasz za jego uaktualnienia.

Ważne

Rozważ samodzielne hostowanie portalu deweloperów tylko wtedy, gdy musisz zmodyfikować rdzeń bazy kodu portalu deweloperów. Ta opcja wymaga zaawansowanej konfiguracji, w tym:

  • Wdrażanie na platformie hostingowej, opcjonalnie z przodu przez rozwiązanie, takie jak CDN, w celu zwiększenia dostępności i wydajności
  • Utrzymywanie infrastruktury hostingu i zarządzanie nią
  • Aktualizacje ręczne, w tym poprawki zabezpieczeń, które mogą wymagać rozwiązania konfliktów kodu podczas uaktualniania bazy kodu

Uwaga

Portal self-hosted nie obsługuje kontroli widoczności i dostępu, które są dostępne w portalu dla deweloperów zarządzanych.

Jeśli pliki multimedialne zostały już przekazane lub zmodyfikowane w portalu zarządzanym, zobacz Przenoszenie z zarządzanego do własnego hostowania w dalszej części tego artykułu.

Wymagania wstępne

Aby skonfigurować lokalne środowisko programistyczne, musisz mieć następujące elementy:

Krok 1. Konfigurowanie środowiska lokalnego

Aby skonfigurować środowisko lokalne, musisz sklonować repozytorium, przełączyć się do najnowszej wersji portalu deweloperów i zainstalować pakiety npm.

  1. Sklonuj repozytorium api-management-developer-portal z usługi GitHub:

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

  2. Przejdź do lokalnej kopii repozytorium:

    cd api-management-developer-portal

  3. Zapoznaj się z najnowszą wersją portalu.

    Przed uruchomieniem poniższego kodu sprawdź bieżący tag wydania w sekcji Wydania repozytorium i zastąp <current-release-tag> wartość najnowszym tagiem wydania.

    git checkout <current-release-tag>

  4. Zainstaluj wszystkie dostępne pakiety npm:

    npm install

Napiwek

Zawsze używaj najnowszej wersji portalu i zachowaj aktualność rozwidlenia portalu. Inżynierowie oprogramowania używają master gałęzi tego repozytorium do codziennych celów programistycznych. Ma niestabilne wersje oprogramowania.

Krok 2. Konfigurowanie plików JSON, statycznej witryny internetowej i ustawień mechanizmu CORS

Portal dla deweloperów wymaga interfejsu API REST usługi API Management do zarządzania zawartością.

plik config.design.json

Przejdź do src folderu i otwórz config.design.json plik.

{
  "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": "..."
      }
  }
}

Skonfiguruj plik:

  1. managementApiUrl W wartości zastąp <service-name> ciąg nazwą wystąpienia usługi API Management. Jeśli skonfigurowano domenę niestandardową, użyj jej zamiast tego (na przykład https://management.contoso.com).

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

  2. Ręcznie utwórz token SAS, aby umożliwić bezpośredni dostęp interfejsu API REST do wystąpienia usługi API Management.

  3. Skopiuj wygenerowany token i wklej go jako managementApiAccessToken wartość.

  4. backendUrl W wartości zastąp <service-name> ciąg nazwą wystąpienia usługi API Management. Jeśli skonfigurowano domenę niestandardową, użyj jej zamiast tego (na przykład https://portal.contoso.com).

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

  5. Jeśli chcesz włączyć funkcję CAPTCHA w portalu dla deweloperów, ustaw wartość "useHipCaptcha": true. Upewnij się, że skonfigurować ustawienia mechanizmu CORS dla zaplecza portalu dla deweloperów.

  6. W systemie w integrationobszarze googleFontsopcjonalnie ustaw apiKey klucz interfejsu API Google, który umożliwia dostęp do interfejsu API dewelopera czcionek internetowych. Ten klucz jest potrzebny tylko wtedy, gdy chcesz dodać czcionki Google w sekcji Style edytora portalu deweloperów.

    Jeśli nie masz jeszcze klucza, możesz go skonfigurować przy użyciu konsoli Google Cloud. Wykonaj te kroki:

    1. Otwórz konsolę Google Cloud.
    2. Sprawdź, czy interfejs API dewelopera czcionek internetowych jest włączony. Jeśli tak nie jest, włącz ją.
    3. Wybierz pozycję Utwórz klucz interfejsu API poświadczeń>.
    4. W otwartym oknie dialogowym skopiuj wygenerowany klucz i wklej go jako wartość apiKey w config.design.json pliku.
    5. Wybierz pozycję Edytuj klucz interfejsu API, aby otworzyć edytor kluczy.
    6. W edytorze w obszarze Ograniczenia interfejsu API wybierz pozycję Ogranicz klucz. Z listy rozwijanej wybierz pozycję Interfejs API dewelopera czcionek internetowych.
    7. Wybierz pozycję Zapisz.

plik config.publish.json

Przejdź do src folderu i otwórz config.publish.json plik.

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

Skonfiguruj plik:

  1. Skopiuj i wklej managementApiUrl wartości i managementApiAccessToken z poprzedniego pliku konfiguracji.

  2. Jeśli chcesz włączyć funkcję CAPTCHA w portalu dla deweloperów, ustaw wartość "useHipCaptcha": true. Upewnij się, że skonfigurować ustawienia mechanizmu CORS dla zaplecza portalu dla deweloperów.

plik config.runtime.json

Przejdź do src folderu i otwórz config.runtime.json plik.

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

Skonfiguruj plik:

  1. Skopiuj i wklej managementApiUrl wartość z poprzedniego pliku konfiguracji.

  2. backendUrl W wartości zastąp <service-name> ciąg nazwą wystąpienia usługi API Management. Jeśli skonfigurowano domenę niestandardową, użyj jej zamiast tego (na przykład https://portal.contoso.com).

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

Konfigurowanie statycznej witryny internetowej

Skonfiguruj funkcję statycznej witryny internetowej na koncie magazynu, podając trasy do indeksu i stron błędów:

  1. Przejdź do konta magazynu w witrynie Azure Portal i wybierz pozycję Statyczna witryna internetowa z menu po lewej stronie.

  2. Na stronie Statyczna witryna internetowa wybierz pozycję Włączone.

  3. W polu Nazwa dokumentu indeksu wprowadź index.html.

  4. W polu Ścieżka dokumentu Błąd wprowadź 404/index.html.

  5. Wybierz pozycję Zapisz.

Konfigurowanie ustawień mechanizmu CORS dla konta magazynu

Skonfiguruj ustawienia współużytkowania zasobów między źródłami (CORS) dla konta magazynu:

  1. Przejdź do konta magazynu w witrynie Azure Portal i wybierz pozycję CORS z menu po lewej stronie.

  2. Na karcie Blob Service skonfiguruj następujące reguły:

    Reguła Wartość
    Dozwolone źródła *
    Dozwolone metody Wybierz wszystkie czasowniki HTTP.
    Dozwolone nagłówki *
    Uwidocznione nagłówki *
    Maksymalny wiek 0

  3. Wybierz pozycję Zapisz.

Konfigurowanie ustawień mechanizmu CORS dla zaplecza portalu dla deweloperów

Skonfiguruj ustawienia mechanizmu CORS dla zaplecza portalu deweloperów, aby zezwolić na żądania pochodzące z portalu deweloperów własnego. Portal dla deweloperów (self-hosted) korzysta z punktu końcowego zaplecza portalu dla deweloperów (ustawionego w backendUrl plikach konfiguracji portalu) w celu włączenia kilku funkcji, w tym:

  • Weryfikacja CAPTCHA
  • Autoryzacja OAuth 2.0 w konsoli testowej
  • Delegowanie uwierzytelniania użytkownika i subskrypcji produktu

Aby dodać ustawienia mechanizmu CORS:

  1. Przejdź do wystąpienia usługi API Management w witrynie Azure Portal i wybierz pozycję Ustawienia portalu>dla deweloperów z menu po lewej stronie.
  2. Na karcie Konfiguracja portalu Self-hosted dodaj co najmniej jedną wartość domeny źródła. Na przykład: .
    • Domena, w której jest hostowany własny portal, na przykład https://www.contoso.com
    • localhost w przypadku programowania lokalnego (jeśli ma to zastosowanie), takich jak http://localhost:8080 lub https://localhost:8080
  3. Wybierz pozycję Zapisz.

Krok 3. Uruchamianie portalu

Teraz możesz skompilować i uruchomić wystąpienie portalu lokalnego w trybie programowania. W trybie programowania wszystkie optymalizacje są wyłączone, a mapy źródłowe są włączone.

Uruchom następujące polecenie:

npm start

Po krótkim czasie domyślna przeglądarka zostanie automatycznie otwarta z lokalnym wystąpieniem portalu deweloperów. Adres domyślny to http://localhost:8080, ale port może ulec zmianie, jeśli 8080 jest już zajęty. Wszelkie zmiany w bazie kodu projektu wyzwalają ponowne kompilowanie i odświeżanie okna przeglądarki.

Krok 4. Edytowanie za pomocą edytora wizualizacji

Za pomocą edytora wizualizacji wykonaj następujące zadania:

  • Dostosowywanie portalu
  • Tworzenie zawartości
  • Organizowanie struktury witryny internetowej
  • Stylizowanie jego wyglądu

Zobacz Samouczek: uzyskiwanie dostępu i dostosowywanie portalu deweloperów. Obejmuje ona podstawowe informacje o interfejsie użytkownika administracyjnego i zawiera listę zalecanych zmian w domyślnej zawartości. Zapisz wszystkie zmiany w środowisku lokalnym i naciśnij klawisze Ctrl+C , aby go zamknąć.

Krok 5. Publikowanie lokalne

Dane portalu pochodzą z postaci obiektów typu silnego. Następujące polecenie tłumaczy je na pliki statyczne i umieszcza dane wyjściowe w ./dist/website katalogu:

npm run publish

Krok 6. Przekazywanie plików statycznych do obiektu blob

Użyj interfejsu wiersza polecenia platformy Azure, aby przekazać lokalnie wygenerowane pliki statyczne do obiektu blob i upewnić się, że odwiedzający mogą do nich przejść:

  1. Otwórz wiersz polecenia systemu Windows, program PowerShell lub inną powłokę poleceń.

  2. Uruchom następujące polecenie interfejsu wiersza polecenia platformy Azure.

    Zastąp <account-connection-string> element parametry połączenia konta magazynu. Możesz go pobrać z sekcji Klucze dostępu konta magazynu.

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

Krok 7. Przejście do witryny internetowej

Witryna internetowa jest teraz aktywna pod nazwą hosta określoną we właściwościach usługi Azure Storage (podstawowy punkt końcowy w statycznych witrynach internetowych).

Krok 8. Zmienianie szablonów powiadomień usługi API Management

Zastąp adres URL portalu deweloperów w szablonach powiadomień usługi API Management, aby wskazać własny portal. Zobacz Jak skonfigurować powiadomienia i szablony wiadomości e-mail w usłudze Azure API Management.

W szczególności należy wprowadzić następujące zmiany w szablonach domyślnych:

Uwaga

Wartości w poniższych sekcjach Zaktualizowano zakładają, że hostujesz portal pod adresem https://portal.contoso.com/.

Potwierdzenie zmiany wiadomości e-mail

Zaktualizuj adres URL portalu dla deweloperów w szablonie powiadomienia o zmianie wiadomości e-mail z potwierdzeniem :

Oryginalna zawartość

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

Zaktualizowana

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

Potwierdzenie nowego konta dewelopera

Zaktualizuj adres URL portalu deweloperów w szablonie powiadomienia z potwierdzeniem nowego konta dewelopera:

Oryginalna zawartość

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

Zaktualizowana

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

Zaproś użytkownika

Zaktualizuj adres URL portalu dla deweloperów w szablonie powiadomienia zaproś użytkownika :

Oryginalna zawartość

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

Zaktualizowana

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

Aktywowano nową subskrypcję

Zaktualizuj adres URL portalu dla deweloperów w szablonie powiadomień Aktywowana nowa subskrypcja :

Oryginalna zawartość

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!

Zaktualizowana

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!

Oryginalna zawartość

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

Zaktualizowana

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

Oryginalna zawartość

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

Zaktualizowana

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

Oryginalna zawartość

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

Zaktualizowana

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

Potwierdzenie zmiany hasła

Zaktualizuj adres URL portalu dla deweloperów w szablonie powiadomienia potwierdzenia zmiany hasła:

Oryginalna zawartość

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

Zaktualizowana

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

Wszystkie szablony

Zaktualizuj adres URL portalu dla deweloperów w dowolnym szablonie, który ma link w stopce:

Oryginalna zawartość

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

Zaktualizowana

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

Przechodzenie z portalu zarządzanego do portalu dla deweloperów( self-hosted)

W czasie wymagania biznesowe mogą ulec zmianie. Możesz skończyć w sytuacji, w której zarządzana wersja portalu deweloperów usługi API Management nie spełnia już Twoich potrzeb. Na przykład nowe wymaganie może wymusić utworzenie niestandardowego widżetu zintegrowanego z dostawcą danych innej firmy. W przeciwieństwie do wersji manged, self-hosted wersji portalu zapewnia pełną elastyczność i rozszerzalność.

Proces przejścia

Możesz przejść z wersji zarządzanej do własnej wersji w ramach tego samego wystąpienia usługi API Management. Proces zachowuje modyfikacje wprowadzone w zarządzanej wersji portalu. Upewnij się, że wcześniej utworzono kopię zapasową zawartości portalu. Skrypt kopii zapasowej można znaleźć w scripts folderze repozytorium GitHub portalu deweloperów usługi API Management.

Proces konwersji jest prawie identyczny z konfigurowaniem ogólnego portalu własnego, jak pokazano w poprzednich krokach w tym artykule. W kroku konfiguracji występuje jeden wyjątek. Konto magazynu w config.design.json pliku musi być takie samo jak konto magazynu zarządzanej wersji portalu. Zobacz Samouczek: używanie przypisanej przez system tożsamości maszyny wirtualnej z systemem Linux w celu uzyskania dostępu do usługi Azure Storage za pośrednictwem poświadczeń sygnatury dostępu współdzielonego, aby uzyskać instrukcje dotyczące pobierania adresu URL sygnatury dostępu współdzielonego.

Napiwek

Zalecamy używanie oddzielnego konta magazynu w config.publish.json pliku. Takie podejście zapewnia większą kontrolę i upraszcza zarządzanie usługą hostingową portalu.

Następne kroki