Rozwiązywanie problemów z narzędziem Azure Developer CLI

  • Artykuł

Ten artykuł zawiera rozwiązania typowych problemów, które mogą wystąpić podczas korzystania z interfejsu wiersza polecenia dla deweloperów platformy Azure (azd).

Uzyskiwanie pomocy i przesyłanie opinii

Jeśli nie możesz znaleźć tego, czego szukasz w tym artykule lub chcesz przekazać opinię, możesz opublikować pytania w dyskusjach dotyczących interfejsu wiersza polecenia dla deweloperów platformy Azure.

Usterki można również zgłaszać, otwierając witrynę GitHub Issues w repozytorium GitHub interfejsu wiersza polecenia dewelopera platformy Azure.

Korzystanie z przełącznika --debug

Jeśli podczas pracy z azdprogramem wystąpi nieoczekiwany problem, uruchom ponownie polecenie z przełącznikiem --debug , aby włączyć dodatkowe debugowanie i dane wyjściowe diagnostyczne.

azd up --debug

Możesz również wysłać dane wyjściowe debugowania do lokalnego pliku tekstowego w celu zwiększenia użyteczności. Takie podejście umożliwia pozyskiwanie informacji debugowania przez inne systemy monitorowania i może być przydatne podczas zgłaszania problemu w usłudze GitHub.

Ważne

Pamiętaj, aby redagować wszelkie poufne informacje podczas przesyłania dzienników debugowania w usłudze GitHub lub zapisywania ich w innych systemach diagnostycznych.

azd deploy --debug > "<your-file-path>.txt"

Katalog .azure

Interfejs wiersza polecenia dla deweloperów platformy Azure zakłada, że wszystkie katalogi przechowywane w .azure katalogu to środowiska interfejsu wiersza polecenia dla deweloperów platformy Azure. Nie uruchamiaj poleceń interfejsu wiersza polecenia dla deweloperów platformy Azure z katalogu macierzystego użytkownika, który ma zainstalowany interfejs wiersza polecenia platformy Azure.

Nie zalogowano się na platformie Azure lub wygasło token w programie Visual Studio

Po uruchomieniu azd init -t <template-name> w programie Visual Studio zostanie wyświetlony następujący błąd: "Aby uzyskać dostęp zdalny: to repozytorium, należy ponownie uwierzytelnić aplikację Visual StudioOAuth".

Rozwiązanie

Uruchom polecenie azd auth login , aby odświeżyć token dostępu.

Zaktualizowane uprawnienia konta platformy Azure nie są odświeżane w programie azd

Domyślnie azd buforuje poświadczenia i uprawnienia platformy Azure. Jeśli twoje konto platformy Azure ma przypisane nowe role i uprawnienia lub jest dodawane do dodatkowych subskrypcji, te zmiany mogą nie zostać natychmiast odzwierciedlone w pliku azd. Aby rozwiązać ten problem, wyloguj się, a następnie zaloguj się ponownie, używając azd następujących poleceń:

azd auth logout

azd auth login

Postępuj zgodnie z monitami z azd auth login polecenia , aby ukończyć proces logowania i zaktualizować buforowane poświadczenia.

Ograniczenia usługi Cloud Shell dla azd

W usłudze azd Cloud Shell obowiązują pewne ograniczenia:

Obsługa platformy Docker w usłudze Cloud Shell

Usługa Cloud Shell nie obsługuje uruchamiania platformy Docker build lub run poleceń, ponieważ demon platformy Docker nie jest uruchomiony. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z usługą Cloud Shell.

Limit czasu usługi Cloud Shell

Usługa Cloud Shell może upłynął limit czasu podczas długiego wdrażania lub innych długotrwałych zadań. Upewnij się, że sesja nie stanie się bezczynna. Zobacz Limity użycia usługi Cloud Shell.

Interfejs usługi Cloud Shell

Usługa Cloud Shell jest przede wszystkim interfejsem wiersza polecenia i będzie mieć mniej funkcji niż zintegrowane środowisko programistyczne, takie jak Visual Studio Code.

Nie można nawiązać połączenia z demonem platformy Docker w usłudze Cloud Shell

Usługa Cloud Shell używa kontenera do hostowania środowiska powłoki, więc zadania wymagające uruchomienia demona platformy Docker nie są dozwolone.

Instalowanie innej wersji narzędzia azd w usłudze Cloud Shell

W niektórych przypadkach może być konieczne zainstalowanie innej wersji azd niż wersja, która jest już używana w usłudze Cloud Shell. Aby to zrobić w powłoce bash:

  1. Uruchom polecenie mkdir -p ~/bin , aby upewnić się, że ~/bin folder jest obecny
  2. Uruchom polecenie mkdir -p ~/azd , aby upewnić się, że folder lokalny ~/azd jest obecny
  3. Uruchom curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version> polecenie (<version> domyślnie, stable ale można również określić określoną wersję, na 1.0.0 przykład określoną).

Po zainstalowaniu azd wersja symbolicznie połączona w ~/bin programie będzie mieć pierwszeństwo przed wersją azd symbolicznie połączoną w pliku /usr/local/bin.

Aby powrócić do korzystania z wersji programu już zainstalowanej azd w usłudze Cloud Shell w powłoce bash:

  1. Uruchom polecenie rm ~/bin/azd
  2. Uruchom polecenie rm -rf ~/azd

Rozwiązanie

Użyj innego hosta do wykonywania zadań, które wymagają demona platformy Docker. Jedną z opcji jest użycie platformy Docker-machine, zgodnie z opisem w dokumentacji rozwiązywania problemów z usługą Cloud Shell.

Wymaganie interfejsu wiersza polecenia platformy Azure Bicep

azd up i azd provision wymagają najnowszej wersji interfejsu wiersza polecenia platformy Azure Bicep. Może zostać wyświetlony następujący komunikat o błędzie: "Błąd: nie można skompilować szablonu bicep: nie można skompilować szablonu bicep modułu Az programu PowerShell: 1, stdout: , stderr: OSTRZEŻENIE: dostępna jest nowa wersja Bicep: v0.4.1272".

Rozwiązanie

Wcześniej Bicep był preqrequisite do instalowania i używania polecenia azd . azd teraz automatycznie instaluje Bicep w zakresie lokalnym azd (nie globalnie) i ten problem powinien zostać rozwiązany. Jeśli jednak chcesz użyć innej wersji, możesz ustawić zmienną środowiskową: AZD_BICEP_TOOL_PATH aby wskazać lokalizację potrzebnej wersji.

azd up lub azd provision kończy się niepowodzeniem

Czasami coś może być niezręczne z azd up lub azd provision. Typowe błędy obejmują:

  • "Nie można aprowizować niektórych zasobów w regionie świadczenia usługi Azure, ponieważ region jest poza pojemnością".
  • "Odpowiedni dostawca zasobów nie jest obecny w tym regionie".

Kroki rozwiązywania problemów mogą się różnić w zależności od głównej przyczyny.

Rozwiązanie

  1. Przejdź do portalu Azure Portal.

  2. Znajdź grupę zasobów, która jest nazwą rg-your-environment-name<>.

  3. Wybierz pozycję Wdrożenia , aby uzyskać więcej informacji.

  4. Sprawdź, czy określono nazwę środowiska, która jest taka sama jak nazwa środowiska.

  5. Przejdź do https://github.com/<your repo>/actionsstrony , a następnie zapoznaj się z plikiem dziennika w przebiegu potoku, aby uzyskać więcej informacji.

Aby uzyskać informacje o innych zasobach, zobacz Rozwiązywanie typowych błędów wdrażania platformy Azure — Azure Resource Manager.

azd init Wymaga sudo

Przed azd version = azure-dev-cli_0.2.0-beta.1programem azd utwórz .azd folder z dostępem drw-r--r-- .

Spowoduje to problem, ponieważ użycie tej lub dowolnej wcześniejszej wersji w dowolnej konfiguracji systemu Linux (WSL, ssh-remote, devcontainer itp.) udostępnia .azd już folder z trybem tylko do odczytu.

Rozwiązanie

  1. Ręcznie usuń już udostępniony .azd folder:

    rm -r ~/.azd

  2. Uruchom polecenie , azd initazd aby ponownie utworzyć folder z odpowiednimi poziomami dostępu.

azd monitor dla kontenera deweloperskiego

azd monitor program nie jest obecnie obsługiwany, jeśli używasz kontenera programistycznego jako środowiska programistycznego.

Nie można uwierzytelnić się w środowiskach codespaces

Jeśli występują problemy z uwierzytelnianiem w usłudze Codespaces, upewnij się, że szablon Dockerfile zawiera sudo apt-get update && sudo apt-get install xdg-utils polecenia. Polecenie xdg-utils otworzy kartę przeglądarki, która umożliwia logowanie.

Nie można wdrożyć usługi Static Web Apps pomimo komunikatu o powodzeniu

Znany problem występuje podczas wdrażania w usłudze Azure Static Web Apps, w którym domyślne azd up dane wyjściowe mogą oznaczać, że akcja zakończyła się pomyślnie, ale zmiany nie zostały rzeczywiście wdrożone. Ten problem można zdiagnozować, uruchamiając azd up polecenie z włączoną flagą --debug . W dziennikach wyjściowych może zostać wyświetlony następujący komunikat:

Preparing deployment. Please wait...
An unknown exception has occurred

Najprawdopodobniej wystąpi ten problem podczas azd uruchamiania z akcji usługi GitHub. Aby obejść ten problem, po utworzeniu witryny skopiuj staticwebapp.config.json go do folderu kompilacji. Ten krok można zautomatyzować przy użyciu wstępnego pakietu lub wstępnego punktu zaczepienia poleceń, który umożliwia wykonywanie skryptów niestandardowych w różnych punktach w przepływach pracy poleceń azd.

Zespół produktu pracuje nad rozwiązaniem tego problemu.

Błąd funkcji GitHub Actions — "Nie ma uprawnień do uzyskania wpisów tajnych w magazynie kluczy"

Udostępnianie tej samej nazwy środowiska lub grupy zasobów podczas aprowizacji zasobów lokalnie i w funkcji GitHub Actions może spowodować błąd Does not have secrets get permission on key vault.. z usługi Key Vault. Usługa Key Vault nie obsługuje aktualizacji uprawnień przyrostowych za pośrednictwem aplikacji Bicep, co oznacza, że przepływ pracy funkcji GitHub Actions zastępuje uprawnienia zasad dostępu użytkownika lokalnego.

Zalecanym rozwiązaniem tego problemu jest użycie oddzielnych nazw środowisk dla lokalnych przepływów pracy programowania i funkcji GitHub Actions. Przeczytaj więcej na temat korzystania z wielu środowisk za azd env pomocą polecenia na stronie Często zadawane pytania.

Obsługa przeglądarki opartej na tekście

Przeglądarki oparte na tekście nie są obecnie obsługiwane przez azd monitorprogram .

azd pipeline config używanie narzędzia AzDo dla szablonów Języka Java w systemie Windows

Może wystąpić błąd podczas uruchamiania azd pipeline config polecenia AzDo dla szablonów Języka Java w systemie Windows. Na przykład masz:

  1. Uruchom następujące polecenie w systemie Windows:

    azd init --template Azure-Samples/todo-java-mongo
azd pipeline config

  2. Odebrano następujący błąd:

    Screenshot showing the error received when running azd pipeline config with AzDo for Java on Windows.

Rozwiązanie

Jest to znany problem. Podczas rozwiązywania tego problemu spróbuj wykonać następujące polecenie:

git update-index --chmod=+x src/api/mvnw && git commit -m "Fix executable bit permissions" && git push

failed packaging service 'api': failed invoking action 'package', failed to run NPM script build, signal: segmentation fault niepowodzenie po uaktualnieniu azd urządzenia Apple Silicon (M1/M2)

W niektórych sytuacjach uaktualnienie z wersji x86_64 azd do pliku binarnego ARM64 może spowodować błędy szablonów utworzonych przy użyciu x86_64 wersji azd. Jest to spowodowane tym, że szablon używa wersji v8-compile-cache , której można spróbować załadować kod bajtowy skompilowany w ramach x86_64 do procesu ARM64.

Aby rozwiązać ten problem, uaktualnij v8-compile-cache pakiet w projekcie, którego dotyczy problem:

  1. Zmień katalog na usługę, która nie powiodła się (src/api w przypadku failed packaging service 'api')
  2. Uruchom polecenie npm upgrade v8-compile-cache
  3. Zmień katalog na katalog główny repozytorium i ponownie uruchom azd polecenie (np. azd package )azd up

azd pipeline config niepowodzenie z powodu zasad dostępu warunkowego

Podczas uruchamiania azd pipeline configpolecenia może zostać wyświetlony błąd podobny do następującego:

ERROR: failed to create or update service principal: failed retrieving application list, failed executing request: http call(https://login.microsoftonline.com/common/oauth2/v2.0/token)(POST) error: reply status code was 400:
{"error":"invalid_grant","error_description":"AADSTS50005: User tried to log in to a device from a platform (Unknown) that's currently not supported through Conditional Access policy. Supported device platforms are: iOS, Android, Mac, and Windows flavors.\r\nTrace ID: be3438c1-42fc-4c37-96d8-0e723ac54f01\r\nCorrelation ID: f535565f-9f3c-4014-ad65-403f514bf892\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"be3438c1-42fc-4c37-96d8-0e723ac54f01","correlation_id":"f535565f-9f3c-4014-ad65-403f514bf892"}

Ten błąd jest związany z włączaniem dzierżawy usługi Microsoft Entra zasad dostępu warunkowego. Określone zasady wymagają zalogowania się do obsługiwanej platformy urządzeń.

Ten błąd może być również wyświetlany z powodu zalogowania się przy użyciu mechanizmu kodu urządzenia, co uniemożliwia firmie Microsoft Entra wykrywanie platformy urządzenia poprawnie.

Rozwiązanie

Aby skonfigurować przepływ pracy, musisz przyznać usłudze GitHub uprawnienia do wdrażania na platformie Azure w Twoim imieniu. Autoryzowanie usługi GitHub przez utworzenie jednostki usługi platformy Azure przechowywanej w kluczu tajnym usługi GitHub o nazwie AZURE_CREDENTIALS. Wybierz hosta usługi Codespace, aby uzyskać instrukcje:

  1. Upewnij się, że korzystasz z urządzenia wymienionego jako obsługiwane, zgodnie z komunikatem o błędzie.

  2. Uruchom ponownie azd auth login flagę --use-device-code=false dołączona:

    azd auth login --use-device-code=false

  3. Po zalogowaniu może zostać wyświetlony komunikat o localhost refused to connect błędzie. Jeśli tak:

    1. Skopiuj adres URL.
    2. Uruchom curl '<pasted url>' polecenie (adres URL w cudzysłowie) w nowym terminalu usługi Codespaces.

    W oryginalnym terminalu logowanie powinno się teraz zakończyć pomyślnie.

  4. Po zalogowaniu uruchom ponownie polecenie azd pipeline config.