Udostępnij za pośrednictwem

Samodzielne hostowanie portalu deweloperów usługi API Management

DOTYCZY: Deweloper | Podstawowy | Standardowy | 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 hostować samodzielnie wiele portali dla instancji zarządzania API, z różnorodnymi 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 użyciem rozwiązania takiego jak CDN, aby zwiększyć dostępność i wydajność.
  • 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 hostowany samodzielnie nie obsługuje kontroli widoczności i dostępu, które są dostępne w portalu zarządzanym dla deweloperów.

Jeśli już przesłałeś lub zmodyfikowałeś pliki multimedialne w portalu zarządzanym, zapoznaj się z 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

Wskazówka

Zawsze używaj najnowszej wersji portalu i zachowaj rozwidlenie portalu up-to-date. 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. W wartości managementApiUrl zastąp <service-name> 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 do instancji API Management przy użyciu interfejsu REST API.

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

  4. W wartości backendUrl zastąp <service-name> 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. Pamiętaj, aby skonfigurować ustawienia mechanizmu CORS dla zaplecza portalu deweloperskiego.

  6. W integration, w obszarze googleFonts, opcjonalnie ustaw klucz Google API w apiKey, który pozwala na dostęp do Developer API 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 Utwórz poświadczenia>klucz interfejsu API.
    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 programisty czcionek internetowych.
    7. Wybierz 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 wartości managementApiUrl i managementApiAccessToken z poprzedniego pliku konfiguracji.

  2. Jeśli chcesz włączyć funkcję CAPTCHA w portalu dla deweloperów, ustaw wartość "useHipCaptcha": true. Pamiętaj, aby skonfigurować ustawienia mechanizmu CORS dla zaplecza portalu deweloperskiego.

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. W wartości backendUrl zastąp <service-name> 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 magazynowym, podając trasy do strony głównej i strony błędu.

  1. Przejdź do swojego konta usług przechowywania w Azure Portal i wybierz opcję 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łędu wprowadź 404/index.html.

  5. Wybierz Zapisz.

Konfigurowanie ustawień mechanizmu CORS dla konta magazynowego

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 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 deweloperski hostowany lokalnie korzysta z punktu końcowego zaplecza portalu deweloperskiego (ustawionego w backendUrl plikach konfiguracji portalu) w celu włączenia kilku funkcji, w tym:

Aby dodać ustawienia mechanizmu CORS:

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

Krok 3. Uruchamianie portalu

Teraz możesz skompilować i uruchomić lokalną instancję portalu w trybie deweloperskim. 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 otwiera się automatycznie z lokalną instancją portalu programisty. 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
  • Autor treś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 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 zasobu 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 innego interpretera poleceń.

  2. Uruchom następujące polecenie Azure CLI.

    Zastąp <account-connection-string> ciągiem połączenia konta magazynowego. Możesz go pobrać z sekcji Klucze dostępu swojego konta magazynowego.

    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 dewelopera w szablonie powiadomienia potwierdzenie zmiany adresu e-mail:

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 dewelopera w szablonie powiadomienia Zaproszenie 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>

Przejście z zarządzanego portalu na portal dla programistów hostowany samodzielnie

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 zarządzanej, ta samodzielnie hostowana wersja portalu zapewnia pełną elastyczność i rozszerzalność.

Proces przejścia

Możesz przejść z wersji zarządzanej do wersji samodzielnie hostowanej 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 pliku config.design.json musi być takie samo jak konto magazynu wersji zarządzanej portalu. Zobacz Samouczek: użycie tożsamości przypisanej przez system dla maszyny wirtualnej z systemem Linux w celu uzyskania dostępu do Azure Storage za pośrednictwem poświadczenia SAS, aby dowiedzieć się, jak pobrać adres URL SAS.

Wskazówka

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

Powiązana zawartość