Biblioteca principal del SDK de Azure para C++

Azure::Core (azure-core) proporciona primitivos compartidos, abstracciones y asistentes para las bibliotecas cliente modernas del SDK de Azure escritas en C++. Estas bibliotecas siguen las directrices de diseño del SDK de Azure para C++.

La biblioteca permite que las bibliotecas cliente expongan la funcionalidad común de forma coherente. Una vez que aprenda a usar estas API en una biblioteca cliente, sabrá cómo usarlas en otras bibliotecas cliente.

Cómo empezar

Normalmente, no es necesario descargar azure-core; se descargará automáticamente como dependencia de las bibliotecas cliente. En caso de que quiera descargarlo explícitamente (para implementar su propia biblioteca cliente, por ejemplo), puede encontrar el origen en aquí o usar vcpkg para instalar el paquete azure-core-cpp.

Inclusión del paquete

La manera más fácil de adquirir el SDK de C++ es aprovechar el administrador de paquetes vcpkg. Consulte la sección Léame correspondiente del SDK de Azure para C++.

Para instalar el paquete de Azure Core mediante vcpkg:

> vcpkg install azure-core-cpp

A continuación, use en el archivo CMake:

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

Conceptos clave

Los principales conceptos compartidos de Azure::Core incluyen:

  • Control de datos de streaming y entrada/salida (E/S) a través BodyStream de junto con sus tipos derivados.
  • Acceso a los detalles de respuesta HTTP para el modelo devuelto de cualquier operación de cliente del SDK, a través de Response<T>.
  • Sondear las operaciones de ejecución prolongada (LROs), a través de Operation<T>.
  • Excepciones para notificar errores de solicitudes de servicio de forma coherente a través del tipo RequestFailedExceptionde excepción base .
  • Abstracciones para las credenciales del SDK de Azure (TokenCredential).
  • Capa de transporte HTTP reemplazable para enviar solicitudes y recibir respuestas a través de la red.
  • Canalización HTTP y directivas HTTP, como reintento y registro, que se pueden configurar a través de opciones específicas del cliente de servicio.

Operaciones de larga duración

Algunas operaciones tardan mucho tiempo en completarse y requieren sondeos para su estado. Métodos que inician tipos de valor devuelto Operation<T> de operaciones de larga duración.

Puede sondear de forma intermitente si la operación ha finalizado mediante el Poll() método en el devuelto Operation<T> y realizar un seguimiento del progreso de la operación mediante Value(). Como alternativa, si solo desea esperar hasta que se complete la operación, puede usar 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();

Adaptador de transporte HTTP

De forma predeterminada, el SDK de Azure para C++ admite las bibliotecas libcurl y WinHTTP como pilas HTTP para comunicarse con los servicios de Azure a través de la red. El SDK también proporciona un mecanismo para el customer-implementedadaptador de transporte HTTP. Puede obtener más información sobre el adaptador de transporte en este documento.

Solución de problemas

Tres formas principales de solucionar errores son:

Mensajes de registro del SDK

La manera más sencilla de habilitar los registros es establecer AZURE_LOG_LEVEL variable de entorno en uno de los valores: |AZURE_LOG_LEVEL|Azure::Core::Diagnostics::Logger::Level|Nivel de mensaje de registro| |-|-|-| |4 o error o err|Error|Nivel de registro de errores de los que es poco probable que la aplicación se recupere de.| |3 o warning o warn|Warning|Nivel de registro cuando una función no puede realizar su tarea prevista.| |2 o informational, o information o info|Informational|Nivel de registro cuando una función funciona normalmente.| |1, o verbose, o debug|Verbose|Nivel de registro para escenarios detallados de solución de problemas.|

A continuación, los mensajes de registro se imprimirán en la consola (stderr). Tenga en cuenta que stderr los mensajes se pueden redirigir a un archivo de registro como este:

En Windows:

myprogram.exe 2> log.txt

En Linux o macOS:

./myprogram 2> log.txt

Además, los mensajes de registro se pueden procesar mediante programación proporcionando una función de devolución de llamada, que puede guardarlos en un archivo o mostrarlos de forma personalizada deseada.

#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 */ });
}

Tenga en cuenta que la devolución de llamada del agente de escucha se ejecuta en el mismo subproceso que la operación que desencadenó el mensaje de registro. Se recomienda implementar debido a la cantidad mínima de procesamiento de mensajes de registro en el subproceso de devolución de llamada. Cuando se requiera el procesamiento de mensajes, considere la posibilidad de implementar de forma que la devolución de llamada inserte la cadena de mensaje en una cola segura para subprocesos, de modo que otro subproceso elija los mensajes de esa cola y los controle.

Pasos siguientes

Explore e instale las bibliotecas disponibles del SDK de Azure.

Contributing

Para más información sobre cómo contribuir a este repositorio, consulte la guía de contribución.

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia de colaborador (CLA) declarando que tiene derecho a, y en realidad, concedanos los derechos para usar su contribución. Para obtener más información, visite el Contrato de licencia de colaborador.

Al enviar una solicitud de incorporación de cambios, un bot CLA determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios de forma adecuada (por ejemplo, etiqueta, comentario). Solo tiene que seguir las instrucciones proporcionadas por el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el código de conducta de código abierto de Microsoft. Para obtener más información, consulte el Preguntas Frecuentes sobre el Código de Conducta o póngase en contacto con opencode@microsoft.com si tiene preguntas o comentarios adicionales.

Muchas personas de todo el mundo han ayudado a mejorar este proyecto. Querrá echar un vistazo a:

Notificación de problemas de seguridad y errores de seguridad

Los problemas de seguridad y los errores se deben notificar de forma privada, por correo electrónico, al Centro de respuesta de seguridad de Microsoft (MSRC). secure@microsoft.com Debe recibir una respuesta en un plazo de 24 horas. Si por alguna razón no lo hace, siga por correo electrónico para asegurarnos de que recibimos su mensaje original. Puede encontrar más información, incluida la clave PGP de MSRC, en Security TechCenter.

Licencia

El SDK de Azure para C++ tiene licencia bajo la licencia MIT .

  • Se actualizó por última vez el