Condividi tramite

Libreria di base di Azure SDK per C++

Azure::Core (azure-core) fornisce primitive, astrazioni e helper condivisi per le moderne librerie client di Azure SDK scritte in C++. Queste librerie seguono le linee guida per la progettazione di Azure SDK per C++.

La libreria consente alle librerie client di esporre funzionalità comuni in modo coerente. Dopo aver appreso come usare queste API in una libreria client, si saprà come usarle in altre librerie client.

Come iniziare

In genere, non sarà necessario scaricare azure-core. Verrà scaricato per l'utente come dipendenza delle librerie client. Se si vuole scaricarlo in modo esplicito (per implementare la propria libreria client, ad esempio), è possibile trovare l'origine qui oppure usare vcpkg per installare il pacchetto azure-core-cpp.

Includere il pacchetto

Il modo più semplice per acquisire L'SDK C++ è sfruttare la gestione pacchetti vcpkg. Vedere la sezione leggimi di Azure SDK per C++ corrispondente.

Per installare il pacchetto Azure Core tramite vcpkg:

> vcpkg install azure-core-cpp

Usare quindi nel file CMake:

find_package(azure-core-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-core)

Concetti chiave

I principali concetti condivisi di Azure::Core includono:

  • Gestione dei dati di streaming e input/output (I/O) tramite BodyStream insieme ai relativi tipi derivati.
  • Accesso ai dettagli della risposta HTTP per il modello restituito di qualsiasi operazione client SDK tramite Response<T>.
  • Esecuzione del polling di operazioni a esecuzione prolungata (LRO) tramite Operation<T>.
  • Eccezioni per la segnalazione di errori da richieste di servizio in modo coerente tramite il tipo di eccezione di RequestFailedExceptionbase .
  • Astrazioni per le credenziali di Azure SDK (TokenCredential).
  • Livello di trasporto HTTP sostituibile per inviare richieste e ricevere risposte in rete.
  • Pipeline HTTP e criteri HTTP, ad esempio la ripetizione dei tentativi e la registrazione, configurabili tramite opzioni specifiche del client del servizio.

Operazioni a esecuzione prolungata

Il completamento di alcune operazioni richiede molto tempo e richiede il polling per il relativo stato. I metodi che avviano le operazioni a esecuzione prolungata restituiscono Operation<T> tipi.

È possibile eseguire un polling intermittente se l'operazione è stata completata usando il metodo sull'avanzamento Poll() restituito e tenere traccia dell'avanzamento Operation<T> dell'operazione usando Value(). In alternativa, se si vuole attendere il completamento dell'operazione, è possibile usare PollUntilDone().

SomeServiceClient client;

auto operation = *client.StartSomeLongRunningOperation();

while (!operation.IsDone())
{
  std::unique_ptr<Http::RawResponse> response = operation.Poll();

  auto partialResult = operation.Value();

  // Your per-polling custom logic goes here, such as logging progress.

  // You can also try to abort the operation if it doesn't complete in time.

  std::this_thread::sleep_for(std::chrono::milliseconds(1000));
}

auto finalResult = operation.Value();

Adapter trasporto HTTP

Azure SDK per C++ supporta le librerie libcurl e WinHTTP come stack HTTP per la comunicazione con i servizi di Azure in rete. L'SDK fornisce anche un meccanismo per customer-implementedl'adattatore di trasporto HTTP. Altre informazioni sull'adattatore di trasporto sono disponibili in questo documento.

Risoluzione dei problemi

I tre modi principali per la risoluzione degli errori sono:

  • Controllo delle eccezioni
  • Abilitazione della registrazione (vedere Sdk Log Messages)

Messaggi di log sdk

Il modo più semplice per abilitare i log consiste nell'impostare la AZURE_LOG_LEVEL variabile di ambiente su uno dei valori: ||AZURE_LOG_LEVELAzure::Core::Diagnostics::Logger::Level|Livello di messaggio di log |-|-|-| |4, o erroro|errError |Livello di registrazione per gli errori da cui è improbabile che l'applicazione venga ripristinata.| |3, o warningo|warnWarning |Livello di registrazione quando una funzione non riesce a eseguire l'attività desiderata.| |2, o informationalinformationo o info|Informational|Livello di registrazione quando una funzione funziona normalmente.| |1, o verboseo|debugVerbose |Livello di registrazione per scenari di risoluzione dei problemi dettagliati.|

I messaggi di log verranno quindi stampati nella console (stderr). Si noti che stderr i messaggi possono essere reindirizzati in un file di log simile al seguente:

In Windows:

myprogram.exe 2> log.txt

In Linux o macOS:

./myprogram 2> log.txt

Inoltre, i messaggi di log possono essere elaborati a livello di codice fornendo una funzione di callback, che può salvarli in un file o visualizzarli in modo personalizzato desiderato.

#include <azure/core/diagnostics/logger.hpp>

int main()
{
    using namespace Azure::Core::Diagnostics;

    // See above for the level descriptions.
    Logger::SetLevel(Logger::Level::Verbose);

    // SetListener accepts std::function<>, which can be either lambda or a function pointer.
    Logger::SetListener([&](auto lvl, auto msg){ /* handle Logger::Level lvl and std::string msg */ });
}

Si noti che il callback del listener viene eseguito nello stesso thread dell'operazione che ha attivato il messaggio di log. È consigliabile eseguire l'implementazione a causa della quantità minima di elaborazione dei messaggi di log nel thread di callback. Quando è necessaria l'elaborazione dei messaggi, è consigliabile implementare in modo che il callback inserisca la stringa di messaggio in una coda thread-safe, in modo che un altro thread rilevi i messaggi dalla coda e li gestisca.

Passaggi successivi

Esplorare e installare le librerie di Azure SDK disponibili.

Contributing

Per informazioni dettagliate sul contributo a questo repository, vedere la guida per i contributi.

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo. Per informazioni dettagliate, visitare il Contratto di licenza collaboratore.

Quando si invia una richiesta pull, un bot CLA determinerà automaticamente se è necessario fornire un cla e decorare la richiesta pull in modo appropriato (ad esempio, etichetta, commento). Seguire semplicemente le istruzioni fornite dal bot. Dovrai eseguire questa operazione una sola volta in tutti i repository usando la nostra cla.

Questo progetto ha adottato il codice di comportamento open source Microsoft. Per altre informazioni, vedere domande frequenti sul codice di comportamento o contattare opencode@microsoft.com con eventuali domande o commenti aggiuntivi.

Molte persone in tutto il mondo hanno contribuito a migliorare questo progetto. Si vuole eseguire il check-out:

Segnalazione di problemi di sicurezza e bug di sicurezza

I problemi di sicurezza e i bug devono essere segnalati privatamente, tramite posta elettronica, al Microsoft Security Response Center (MSRC). secure@microsoft.com La risposta viene inviata in genere entro 24 ore. Se per qualche motivo non lo fai, segui tramite posta elettronica per assicurarti che il tuo messaggio originale sia stato ricevuto. Altre informazioni, inclusa la chiave PGP MSRC, sono disponibili in Security TechCenter.

Licenza

Azure SDK per C++ è concesso in licenza con la licenza MIT .

  • Last updated on