Pojęcia dotyczące programowania rozszerzeń

Rozszerzenia azd () dodają nowe polecenia, automatyzują przepływy pracy i integrują inne usługi z azd. W tym artykule wyjaśniono pojęcia, które należy zrozumieć przed utworzeniem rozszerzenia, takiego jak narzędzia deweloperskie, zestaw SDK (Software Development Kit) i sposób azd komunikowania się z uruchomionym rozszerzeniem. Aby dowiedzieć się, jakie rozszerzenia są z perspektywy użytkownika, zobacz omówienie rozszerzeń.

Rozszerzenie dla deweloperów

Najszybszym sposobem kompilowania rozszerzeń jest użycie rozszerzenia dewelopera azd (microsoft.azd.extensions). Rozszerzenie dla deweloperów dodaje zestaw poleceń w przestrzeni nazw azd x, służących do tworzenia szkieletu, kompilowania, pakowania i publikowania rozszerzenia:

W przewodniku Szybki start: tworzenie przykładowego rozszerzenia pokazano, jak zainstalować rozszerzenie dla deweloperów i utworzyć strukturę pierwszego rozszerzenia.

Rozszerzenie dla deweloperów obsługuje procesy publikowania oparte na rejestrze oraz dystrybucję przenośnych pakietów. Użyj azd x pack, aby tworzyć artefakty platformy na potrzeby publikacji wydania i w rejestrze, lub utwórz samodzielny pakiet .zip, gdy chcesz udostępnić rozszerzenie bez konieczności hostowania rejestru. Pakiety można instalować z pliku lokalnego lub hostowane zdalnie pod adresem URL HTTPS. Aby uzyskać szczegółowe wskazówki, zobacz Publikowanie rozszerzenia.

Platforma rozszerzeń i gRPC

azd i rozszerzenia działają jako oddzielne procesy, które komunikują się za pośrednictwem gRPC. Podczas wywoływania polecenia rozszerzenia są wykonywane następujące kroki:

1. azd Uruchamia serwer gRPC na losowym porcie i ustawia AZD_SERVER zmienną środowiskową z adresem serwera.
2. azd ustawia zmienną środowiskową AZD_ACCESS_TOKEN, której wartością jest podpisany token JWT (JSON Web Token), przyznający rozszerzeniu dostęp do usług azd na czas działania polecenia.
3. azd wywołuje polecenie rozszerzenia i przekazuje bieżące argumenty, flagi i zmienne środowiskowe.
4. Twoje rozszerzenie używa klienta gRPC, aby komunikować się z powrotem z azd za pośrednictwem usług frameworka, takich jak wyświetlanie monitów użytkownikowi lub odczytywanie konfiguracji projektu.
5. azd czeka na zakończenie polecenia i zgłasza niezerowy kod zakończenia jako błąd.

Ten model umożliwia rozszerzeń interakcję ze azd spójnym, bezpiecznym sposobem bez bezpośredniego uzyskiwania dostępu do stanu wewnętrznego azd .

Wymagania dotyczące rozszerzenia na poziomie projektu

Projekty mogą deklarować rozszerzenia, których wymagają w programie azure.yaml. Użyj sekcji requiredVersions.extensions, aby wymienić identyfikatory rozszerzeń i ograniczenia wersji, tak aby azd mogło określić wersje spełniające wymagania projektu.

requiredVersions:
  extensions:
    azure.ai.agents: ">=1.0.0"
    contoso.azd.tagger: "^2.0.0"

Zadeklaruj wymagane rozszerzenia, gdy projekt zależy od hostów i dostawców udostępnianych przez rozszerzenia, modułów obsługi cyklu życia, walidacji lub poleceń. Aby uzyskać dokładną składnię schematu i obsługiwanej wersji, zobacz requiredVersions.

azdext SDK

Pakiet azdext to zestaw GO SDK dla platformy rozszerzeń. Zapewnia on klienta gRPC i pomocników obsługujących szczegóły komunikacji, dzięki czemu można skoncentrować się na logice rozszerzenia. Pakiet SDK zawiera narzędzia pomocnicze do:

• Utwórz polecenie główne, które rejestruje standardowe azd flagi oraz obsługę zmiennych środowiskowych.
• Dołącz token dostępu azd do wychodzących żądań.
• Wywołaj azd usługi frameworka, takie jak Project, Environment, Account i Prompt.
• Zgłaszaj nazwane zdarzenia użycia za pośrednictwem interfejsu API gRPC TelemetryService.ReportUsage dla rozszerzeń z oficjalnych źródeł. Aby uzyskać szczegółowe informacje o użyciu interfejsu API, zobacz Komunikacja z azd przy użyciu zestawu SDK.
• Rejestruj procedury obsługi zdarzeń cyklu życia i niestandardowych dostawców za pośrednictwem hosta rozszerzeń.

Aby dowiedzieć się, jak wywoływać usługi azd z poziomu rozszerzenia, zobacz Komunikowanie się z azd przy użyciu zestawu SDK.

Możliwości rozszerzenia

Możliwości deklarują, co może zrobić rozszerzenie. Wyświetl listę możliwości rozszerzenia w manifeście extension.yaml i azd przyznaje odpowiednie uprawnienia w czasie wykonywania. Dostępne możliwości obejmują:

• custom-commands: Dodaj nowe grupy poleceń i polecenia do azd.
• lifecycle-events: Subskrybuj zdarzenia cyklu życia projektu i usługi, takie jak preprovision i postdeploy.
• mcp-server: Podaj narzędzia protokołu MCP (Model Context Protocol) dla agentów sztucznej inteligencji.
• service-target-provider: Podaj niestandardowe cele wdrożenia usługi.
• framework-service-provider: Obsługa kompilacji niestandardowych języków i frameworków.
• provisioning-provider: Zapewnianie dostosowanego procesu aprowizacji infrastruktury.
• validation-provider: Dodaj kontrole walidacji do potoku walidacji azd.
• metadata: Udostępniaj rozbudowane metadane poleceń i konfiguracji na potrzeby danych wyjściowych pomocy oraz funkcji IntelliSense.

Aby dowiedzieć się, jak dodać możliwości do rozszerzenia, zobacz Dodawanie możliwości rozszerzenia.

Obsługiwane języki

Możesz tworzyć rozszerzenia azd w dowolnym języku, który obsługuje gRPC, a azd x init zawiera szablony startowe dla kilku języków. Język Go ma najbardziej kompletną obsługę, w tym pomocników zestawu SDK pierwszej klasy azdext , więc artykuły w tej sekcji używają języka Go dla wszystkich przykładów.

W przypadku rozszerzeń napisanych w językach innych niż Go można wygenerować klientów gRPC z plików proto z repozytorium azure/azure-dev. Aby uzyskać informacje na temat bieżącego stanu obsługi języka, zobacz dokumentację nadrzędnej platformy rozszerzeń.

Rejestry rozszerzeń

Dystrybuujesz rozszerzenia za pośrednictwem źródeł rejestru lub pakietów rozszerzeń. Źródła rejestru to manifesty oparte na adresach URL lub plikach, które opisują dostępne rozszerzenia i ich artefakty. Pakiety rozszerzeń to pakiety przenośne .zip , które można zainstalować bezpośrednio z pliku lokalnego lub hostować zdalnie pod adresem URL HTTPS, gdy nie chcesz hostować rejestru.

• Oficjalny rejestr jest wstępnie skonfigurowany w azd i hostuje zweryfikowane, własne rozszerzenia. Oficjalne rozszerzenia są tworzone w forku repozytorium azure/azure-dev.
• Źródła oparte na adresach URL umożliwiają instalowanie z zdalnych manifestów rejestru publicznego lub prywatnego.
• Źródła oparte na plikach umożliwiają instalowanie z lokalnych manifestów rejestru na potrzeby scenariuszy tworzenia, testowania lub offline.
• Rejestry deweloperskie i nocne to opcjonalne źródła rozszerzeń będących w trakcie opracowywania oraz własnych rozszerzeń tworzonych automatycznie. Rozszerzenia w rejestrze deweloperów są niepodpisane, nieobjęte pomoc techniczna platformy Azure i mogą ulec zmianie lub usunięciu bez powiadomienia.

Aby dowiedzieć się, jak opublikować rozszerzenie w rejestrze, zobacz Publikowanie rozszerzenia.

Treści powiązane

• Tworzenie przykładowego rozszerzenia
• Definiowanie manifestu rozszerzenia
• Dodawanie możliwości rozszerzenia