SDK do Azure Core Library for C++

O Azure::Core (azure-core) fornece primitivas partilhadas, abstrações e auxiliares para bibliotecas clientes modernas do SDK do Azure escritas em C++. Estas bibliotecas seguem as Diretrizes de Design do SDK do Azure para C++.

A biblioteca permite que as bibliotecas clientes exponham funcionalidades comuns de forma consistente. Depois de aprender a usar estas APIs numa biblioteca cliente, vai saber como usá-las noutras bibliotecas clientes.

Como Começar

Normalmente, não precisará de descarregar azure-core; será descarregado para si como uma dependência das bibliotecas clientes. Caso queira descarregá-lo explicitamente (para implementar a sua própria biblioteca cliente, por exemplo), pode encontrar o código-fonte aqui, ou usar vcpkg para instalar o pacote azure-core-cpp.

Inclua o pacote

A forma mais fácil de adquirir o SDK C++ é aproveitar o gestor de pacotes vcpkg. Consulte a secção correspondente do SDK do Azure para readme em C++.

Para instalar o pacote Azure Core via vcpkg:

> vcpkg install azure-core-cpp

Depois, use no seu ficheiro CMake:

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

Conceitos-chave

Os principais conceitos partilhados de Azure::Core incluem:

  • Gestão de dados em streaming e entrada/saída (I/O) juntamente BodyStream com os seus tipos derivados.
  • Aceder aos detalhes de resposta HTTP para o modelo devolvido de qualquer operação de cliente SDK, via Response<T>.
  • Sondagem de operações de longa duração (LROs), via Operation<T>.
  • Exceções para reportar erros de pedidos de serviço de forma consistente através do tipo RequestFailedExceptionbase de exceção .
  • Abstrações para credenciais SDK do Azure (TokenCredential).
  • Camada de transporte HTTP substituível para enviar pedidos e receber respostas através da rede.
  • HTTP pipeline e políticas HTTP como retentativa e registo, que são configuráveis através de opções específicas do cliente de serviço.

Operações de longa duração

Algumas operações demoram muito tempo a concluir e exigem sondagens para saber o seu estado. Os métodos que iniciam operações de longa duração devolvem Operation<T> tipos.

Pode-se interrogar intermitentemente se a operação terminou usando o Poll() método no retorno Operation<T> e acompanhar o progresso da operação usando Value(). Alternativamente, se quiser apenas esperar até a operação terminar, pode 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 fábrica, o SDK do Azure para C++ suporta as bibliotecas libcurl e WinHTTP como pilhas HTTP para comunicar com os serviços Azure através da rede. O SDK também fornece um mecanismo para customer-implementedadaptador de transporte HTTP. Podes saber mais sobre o adaptador de transporte neste documento.

Solução de problemas

Três formas principais de resolver falhas são:

Mensagens de Registo do SDK

A forma mais simples de ativar logs é definir AZURE_LOG_LEVEL variável de ambiente para um dos valores: |AZURE_LOG_LEVEL|Azure::Core::Diagnostics::Logger::Level|Log message level| |-|-|-| |4, ou error, ou err|Error|Nível de registo para falhas das quais a aplicação dificilmente recuperará.| |3, ou warning, ou warn|Warning|Nível de registo quando uma função falha em executar a sua tarefa pretendida.| |2, ou informational, ou information, ou info|Informational|Nível de registo quando uma função funciona normalmente.| |1, ou verbose, ou debug|Verbose|Nível de registo para cenários detalhados de resolução de problemas.|

Depois, as mensagens de registo serão impressas na consola (stderr). Note que stderr as mensagens podem ser redirecionadas para um ficheiro de registo como este:

No Windows:

myprogram.exe 2> log.txt

No Linux ou macOS:

./myprogram 2> log.txt

Além disso, as mensagens de registo podem ser processadas programaticamente através de uma função de callback, que pode guardá-las num ficheiro ou exibi-las de forma personalizada desejada.

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

Note-se que o callback do ouvinte é executado na mesma thread da operação que desencadeou a mensagem de log. É uma implementação recomendada devido à quantidade mínima de processamento de mensagens de registo no thread de callback. Quando for necessário processamento de mensagens, considere implementar de forma a que o callback empurre a cadeia de mensagens para uma fila thread-safe, para que outro thread escolha as mensagens dessa fila e as trate.

Próximos passos

Explore e instale as bibliotecas disponíveis do SDK do Azure.

Contributing

Para mais detalhes sobre como contribuir para este repositório, consulte o guia de contribuições.

Este projeto acolhe contribuições e sugestões. A maioria das contribuições exige que você concorde com um Contrato de Licença de Colaborador (CLA) declarando que você tem o direito de, e realmente concede, os direitos de usar sua contribuição. Para mais detalhes, visite o Acordo de Licença de Contribuidor.

Quando você envia uma solicitação pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar o PR adequadamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta Open Source da Microsoft. Para obter mais informações, consulte o de perguntas frequentes sobre o Código de Conduta ou entre em contato com para obter perguntas ou comentários adicionais.

Muitas pessoas em todo o mundo ajudaram a tornar este projeto melhor. Vai querer espreitar:

Reportar problemas de segurança e bugs de segurança

Problemas de segurança e bugs devem ser reportados de forma privada, por email, ao Centro de Resposta de Segurança da Microsoft (MSRC secure@microsoft.com). Deverá receber uma resposta no prazo de 24 horas. Se, por algum motivo, não o fizer, por favor contacte-nos por e-mail para garantir que recebemos a sua mensagem original. Mais informações, incluindo a chave MSRC PGP, podem ser encontradas no Security TechCenter.

Licença

O SDK do Azure para C++ está licenciado sob a licença MIT .

  • Última atualização a