Freigegebene Azure Core-Bibliothek für Java – Version 1.45.0

Azure Core bietet freigegebene Grundtypen, Abstraktionen und Hilfsprogramme für moderne Java Azure SDK-Clientbibliotheken. Diese Bibliotheken entsprechen den Azure SDK-Entwurfsrichtlinien für Java und können leicht durch Paketnamen ab com.azure und Modulnamen ab azure-identifiziert werden, z. B. com.azure.storage.blobs im /sdk/storage/azure-storage-blob Verzeichnis. Eine ausführlichere Liste der Clientbibliotheken, die Azure Core verwenden, finden Sie hier.

Azure Core ermöglicht Clientbibliotheken, allgemeine Funktionen konsistent verfügbar zu machen. Sobald Sie erfahren, wie Sie diese APIs in einer Clientbibliothek verwenden, wissen Sie, wie sie in anderen Clientbibliotheken verwendet werden.

Erste Schritte

Voraussetzungen

• Java Development Kit (JDK), Version 8 oder höher.

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der General Availability (GA)-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein. In der Regel müssen Sie Azure Core nicht installieren oder davon abhängig sein, sondern wird von Ihrem Buildtool transitiv heruntergeladen, wenn Sie von Clientbibliotheken abhängig sind, die es verwenden.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-core</artifactId>
    </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core</artifactId>
    <version>1.45.0</version>
</dependency>

Wichtige Begriffe

Zu den wichtigsten Konzepten von Azure Core (und damit allen Azure-Clientbibliotheken, die Azure Core verwenden) gehören:

• Konfigurieren von Dienstclients, z. B. Konfigurieren von Wiederholungen, Protokollierung usw. (HttpTrait<T>, ConfigurationTrait<T>usw.)
• Zugreifen auf HTTP-Antwortdetails (Response<T>).
• Aufrufen von Vorgängen mit langer Ausführungsdauer (PollerFlux<T>).
• Paging und asynchrone Datenströme (ContinuablePagedFlux<T>).
• Ausnahmen für die konsistente Meldung von Fehlern aus Dienstanforderungen.
• Abstraktionen für die Darstellung von Azure SDK-Anmeldeinformationen.
• Vorgangstimeouts

Diese werden anhand der unten dargestellten Beispiele vorgestellt.

Beispiele

Zugreifen auf HTTP-Antwortdetails mithilfe von Response<T>

Dienstclients verfügen über Methoden, die Azure-Dienste aufrufen. Rufen Sie diese Methoden dienstmethoden auf.

Dienstmethoden können einen freigegebenen Azure Core-Typ Response<T>zurückgeben. Dieser Typ bietet Zugriff auf das deserialisierte Ergebnis des Dienstaufrufs und auf die Details der vom Server zurückgegebenen HTTP-Antwort.

HTTP-Pipelines mit HttpPipeline

HttpPipeline ist ein Konstrukt, das eine Liste enthält, der HttpPipelinePolicy auf eine Anforderung sequenziell angewendet wird, um sie vorzubereiten, die von einem HttpClientgesendet wird.

Ausnahmehierarchie mit AzureException

AzureException ist die Stamm-Ausnahme in der Hierarchie, die in Azure Core verwendet wird. Zusätzliche Ausnahmen wie HttpRequestException und HttpResponseException werden verwendet, um den Umfang der Ausnahmegründe zu reduzieren.

Paginierung mit ContinuablePagedFlux<T>

ContinuablePageFlux verwaltet das Senden einer anfänglichen Seitenanforderung an einen Dienst und das Abrufen zusätzlicher Seiten, wenn der Consumer weitere Daten anfordert, bis der Consumer die Verarbeitung abgeschlossen hat oder alle Seiten genutzt wurden.

Vorgänge mit langer Ausführungsdauer mit PollerFlux<T>

PollerFlux verwaltet das Senden einer anfänglichen Dienstanforderung und das Anfordern von Verarbeitungsupdates in einem Fixintervall, bis die Abfrage abgebrochen wird oder einen Terminalstatus erreicht.

Konfigurieren von Generatoren

Generatoren werden verwendet, um Dienstclients und einige TokenCredential Implementierungen zu erstellen. Sie können mit einer Vielzahl von Optionen konfiguriert werden, einschließlich HttpPipeline und HttpClient für HTTP-basierte Clients und allgemeinere Optionen wie Configuration undendpoint. Um eine einfachere Integration in Frameworks wie Spring zu ermöglichen und generische Methoden für alle Builder azure-core zuzulassen, stellt eine Reihe von Schnittstellen bereit, die implementiert werden können, um die erforderliche Funktionalität bereitzustellen.

HttpTrait

HttpTrait<T> enthält Methoden zum Festlegen von Schlüsselkonfigurationen für HTTP-basierte Clients. Mit dieser Schnittstelle können Sie die HttpClient, , HttpPipelineHttpPipelinePolicys, RetryOptions, HttpLogOptionsund ClientOptions konfigurieren (vorzugsweiseHttpClientOptions, da sie spezifischer für HTTP-basierte Dienstclients ist).

Für Generatoren, die verfügbar machen HttpTrait<T>, wenn ein HttpPipeline oder HttpClient nicht festgelegt ist, wird eine Standard-instance basierend auf Klassenpfadkonfigurationen und basierend ClientOptions auf dem Generator erstellt. Dies kann zu Verwirrung führen, wenn Sie ein bestimmtes Verhalten für Ihren Client erwarten, z. B. die Verwendung eines Proxys, der nicht aus der Umgebung geladen wurde. Um dies zu vermeiden, empfiehlt es sich, immer die HttpPipeline oder HttpClient in allen Clients festzulegen, wenn Sie erstellen, wenn Ihre Konfigurationen nicht auf der Umgebung basieren, in der die Anwendung ausgeführt wird.

Merkmale von Anmeldeinformationen

Azure Core bietet verschiedene Anmeldeinformationen für die Authentifizierung bei Azure-Diensten. Jeder Anmeldeinformationstyp verfügt über ein entsprechendes Merkmal, das implementiert werden kann, um die Anmeldeinformationen für den Client-Generator bereitzustellen. In der folgenden Tabelle sind die Anmeldeinformationsmerkmale und der entsprechende Anmeldeinformationstyp aufgeführt.

ConfigurationTrait

ConfigurationTrait<T> ermöglicht das Festlegen Configuration auf Dienstclients. Configuration kann verwendet werden, um eine Reihe von Laufzeitverhaltensarten an den Client-Generator zu übergeben, z. B. wie ProxyOptions aus der Umgebung geladen wird, implizit Anmeldeinformationen an einige Clientbuilder übergeben, die dies unterstützen, und vieles mehr.

EndpointTrait

EndpointTrait<T> ermöglicht das Festlegen des Dienstendpunkts auf Dienstclients.

Vorgangstimeouts

Azure SDKs bieten einige konsistente Möglichkeiten zum Konfigurieren von Timeouts für API-Aufrufe. Jedes Timeout wirkt sich auf einen anderen Bereich der Azure SDKs und der aufrufenden Anwendung aus.

HTTP-Timeouts

HTTP-Timeouts sind die niedrigste Timeoutebene für die Verarbeitung der Azure SDKs. Diese Timeouts können beim Erstellen HttpClientvon s oder beim Erstellen von HttpClientOptions Dienstclients konfiguriert werden, ohne selbst zu HttpClient konfigurieren. In der folgenden Tabelle sind das HTTP-Timeout, die entsprechende HttpClientOptions Methode, die zum Festlegen verwendet werden kann, die Umgebungsvariable zum Steuern des Standardwerts, der Standardwert, wenn der Umgebungswert nicht festgelegt ist, und eine kurze Beschreibung der Auswirkungen des Timeouts aufgeführt.

Da diese Timeouts dem Netzwerk am nächsten sind, werden sie, wenn sie ausgelöst werden, über das zurückverbreitet und in der HttpPipeline Regel von erneut RetryPolicyausgeführt werden.

HttpPipeline-Timeouts

HttpPipeline-Timeouts sind die nächste Ebene des Timeouts, das die Azure SDKs bereitstellen. Diese Timeouts werden mit einem HttpPipelinePolicy konfiguriert und ein Timeout mithilfe von entweder Mono.timeout für asynchrone Anforderungen oder mit einem ExecutorService Timeout get(long, TimeUnit) für synchrone Anforderungen konfiguriert.

Abhängig vom Speicherort innerhalb von HttpPipelinewerden diese Timeouts möglicherweise von und RetryPolicy erneut erfasst. Wenn die Timeoutrichtlinie () ist PER_RETRY , wird das Timeout vom RetryPolicy erfasst, da es nach dem RetryPolicypositioniert wird, daher in seinem Erfassungsbereich, wenn die PER_CALL Anforderung erneut ausgeführt wird, von der Anwendungslogik behandelt werdenHttpPipelinePolicy.getPipelinePosition() muss.

Dienstclienttimeouts

Dienstclienttimeouts sind die höchste Ebene des Timeouts, das von den Azure SDKs bereitgestellt wird. Diese Timeouts werden konfiguriert, indem an synchrone Dienstmethoden übergeben Duration timeout werden, die Timeouts unterstützen, oder mithilfe von Mono.timeout oder Flux.timeout für asynchrone Dienstmethoden.

Da sich diese Timeouts auf dem API-Aufruf selbst befinden, können sie nicht von Wiederholungsmechanismen innerhalb der Azure SDKs erfasst werden und müssen von der Anwendungslogik verarbeitet werden.

Nächste Schritte

Erste Schritte mit Azure-Bibliotheken, die mit Azure Core erstellt werden.

Problembehandlung

Wenn Fehler auftreten, melden Sie Probleme über GitHub Issues oder checken Sie StackOverflow für das Azure Java SDK aus.

Aktivieren der Protokollierung

Azure SDKs für Java bieten einen konsistenten Protokollierungsverlauf, um die Problembehandlung von Anwendungsfehlern zu unterstützen und deren Lösung zu beschleunigen. Die erstellten Protokolle erfassen den Flow einer Anwendung, bevor sie den Endzustand erreichen. Dies trägt zur Ermittlung der Grundursache bei. Informationen zum Aktivieren der Protokollierung finden Sie in der Protokollierungsdokumentation .

HTTP-Anforderungs- und Antwortprotokollierung

Die HTTP-Anforderungs- und Antwortprotokollierung kann aktiviert werden, indem HttpLogDetailLevel in der HttpLogOptions zum Erstellen eines HTTP-basierten Dienstclients oder durch Festlegen der Umgebungsvariablen oder Systemeigenschaft AZURE_HTTP_LOG_DETAIL_LEVELfestgelegt wird. In der folgenden Tabelle werden die gültigen Optionen für AZURE_HTTP_LOG_DETAIL_LEVEL und deren HttpLogDetailLevel Korrelation angezeigt (bei gültigen Optionen wird die Groß-/Kleinschreibung nicht beachtet):

Alle anderen Werte oder nicht unterstützten Werte führen zu HttpLogDetailLevel.NONEoder deaktivierte HTTP-Anforderungs- und Antwortprotokollierung. Die Protokollierung muss aktiviert sein , um HTTP-Anforderungen und -Antworten zu protokollieren. Für die Protokollierung von HTTP-Headern muss die verbose Protokollierung aktiviert sein. In der folgenden Tabelle wird erläutert, welche Protokollierung für die einzelnen HttpLogDetailLevelAktiviert ist:

Mitwirken

Ausführliche Informationen zum Mitwirken an diesem Repository finden Sie im Leitfaden zum Mitwirken.

1. Verzweigen sie
2. Erstellen Ihrer Featurebranch (git checkout -b my-new-feature)
3. Committen Ihrer Änderungen (git commit -am 'Add some feature')
4. Pushen in den Branch (git push origin my-new-feature)
5. Erstellen eines neuen Pull Requests