Biblioteca Principal do SDK do Azure para C++

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

A biblioteca permite que as bibliotecas de clientes exponham a funcionalidade comum de forma consistente. Depois de aprender a usar essas APIs em uma biblioteca de clientes, você saberá como usá-las em outras bibliotecas de clientes.

Como começar

Normalmente, você não precisará baixar azure-core; ele será baixado para você como uma dependência das bibliotecas de cliente. Caso deseje baixá-la explicitamente (para implementar sua própria biblioteca de clientes, por exemplo), você pode encontrar a origem aqui ou usar vcpkg para instalar o pacote azure-core-cpp.

Incluir o pacote

A maneira mais fácil de adquirir o SDK do C++ é aproveitando o gerenciador de pacotes vcpkg. Consulte a seção de leiame do SDK do Azure para C++correspondente.

Para instalar o pacote do Azure Core via vcpkg:

> vcpkg install azure-core-cpp

Em seguida, use em seu arquivo CMake:

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

Conceitos principais

Os principais conceitos compartilhados de Azure::Core incluir:

  • Manipulação de dados de streaming e E/S (entrada/saída) junto BodyStream com seus tipos derivados.
  • Acessando detalhes de resposta HTTP para o modelo retornado de qualquer operação de cliente do SDK, via Response<T>.
  • Operações de longa execução de sondagem (LROs), via Operation<T>.
  • Exceções para relatar erros de solicitações de serviço de forma consistente por meio do tipo RequestFailedExceptionde exceção base.
  • Abstrações para credenciais do SDK do Azure (TokenCredential).
  • Camada de transporte HTTP substituível para enviar solicitações e receber respostas pela rede.
  • Pipeline HTTP e políticas HTTP, como repetição e registro em log, que são configuráveis por meio de opções específicas do cliente de serviço.

Operações de longa duração

Algumas operações levam muito tempo para serem concluídas e exigem sondagem para seu status. Métodos que iniciam operações de execução prolongada retornam Operation<T> tipos.

Você pode sondar intermitentemente se a operação foi concluída usando o Poll() método no retorno Operation<T> e acompanhar o progresso da operação usando Value(). Como alternativa, se você quiser apenas aguardar até a conclusão da operação, poderá 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

Pronto para uso, o SDK do Azure para C++ dá suporte às bibliotecas libcurl e WinHTTP como pilhas HTTP para se comunicar com os serviços do Azure pela rede. O SDK também fornece um mecanismo para customer-implementedo adaptador de transporte HTTP. Você pode saber mais sobre o adaptador de transporte neste documento.

Resolução de problemas

Três maneiras principais de solucionar problemas de falhas são:

Mensagens de log do SDK

A maneira mais simples de habilitar logs é definir AZURE_LOG_LEVEL variável de ambiente para um dos valores: |AZURE_LOG_LEVEL|Azure::Core::Diagnostics::Logger::Level|Nível da mensagem de log| |-|-|-| |4 ou error ou err|Error|Nível de registro em log para falhas das quais é improvável que o aplicativo se recupere.| |3 ou warning ou warn|Warning|Nível de registro em log quando uma função falha ao executar sua tarefa pretendida.| |2 ou informational ou information ou info|Informational|Nível de registro em log quando uma função opera normalmente.| |1 ou verbose ou debug|Verbose|Nível de log para cenários detalhados de solução de problemas.|

Em seguida, as mensagens de log serão impressas no console (stderr). Observe que stderr as mensagens podem ser redirecionadas para um arquivo de log como este:

No Windows:

myprogram.exe 2> log.txt

No Linux ou macOS:

./myprogram 2> log.txt

Além disso, as mensagens de log podem ser processadas programaticamente fornecendo uma função de retorno de chamada, que pode salvá-las em um arquivo ou exibi-las de maneira 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 */ });
}

Observe que o retorno de chamada do ouvinte é executado no mesmo thread que a operação que disparou a mensagem de log. É recomendável a implementação devido à quantidade mínima de processamento de mensagens de log no thread de retorno de chamada. Quando o processamento de mensagens for necessário, considere implementar de uma maneira que o retorno de chamada efetue push da cadeia de caracteres de mensagem para uma fila thread-safe, para que outro thread escolha as mensagens dessa fila e as manipule.

Próximas etapas

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

Contributing

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

Este projeto recebe contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença de Colaborador) declarando que você tem o direito de, e realmente fazer, conceder-nos os direitos de usar sua contribuição. Para obter detalhes, visite o Contrato de Licença de Colaborador.

Ao enviar uma solicitação de pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar a 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 de Software Livre da Microsoft. Para obter mais informações, consulte as perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com perguntas ou comentários adicionais.

Muitas pessoas em todo o mundo ajudaram a melhorar este projeto. Você desejará fazer check-out:

Relatar problemas de segurança e bugs de segurança

Problemas de segurança e bugs devem ser relatados em particular, por email, para o MSRC (Centro de Resposta de Segurança da Microsoft). secure@microsoft.com Deverá receber uma resposta dentro de 24 horas. Se por algum motivo você não fizer isso, siga por email para garantir que recebemos sua mensagem original. Mais informações, incluindo a chave PGP do MSRC, podem ser encontradas no TechCenter de Segurança.

Licença

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

  • Última atualização em