Pustaka Inti Azure SDK untuk C++

Azure::Core (azure-core) menyediakan primitif, abstraksi, dan pembantu bersama untuk pustaka klien Azure SDK modern yang ditulis dalam C++. Pustaka ini mengikuti Panduan Desain Azure SDK untuk C++.

Pustaka memungkinkan pustaka klien untuk mengekspos fungsionalitas umum dengan cara yang konsisten. Setelah Anda mempelajari cara menggunakan API ini di satu pustaka klien, Anda akan tahu cara menggunakannya di pustaka klien lain.

Memulai Langkah Pertama

Biasanya, Anda tidak perlu mengunduh azure-core; itu akan diunduh untuk Anda sebagai dependensi pustaka klien. Jika Anda ingin mengunduhnya secara eksplisit (untuk mengimplementasikan pustaka klien Anda sendiri, misalnya), Anda dapat menemukan sumbernya di sini, atau menggunakan vcpkg untuk menginstal paket azure-core-cpp.

Sertakan paket tersebut

Cara term mudah untuk memperoleh C++ SDK adalah memanfaatkan manajer paket vcpkg. Lihat bagian readme Azure SDK untuk C++ yang sesuai.

Untuk menginstal paket Azure Core melalui vcpkg:

> vcpkg install azure-core-cpp

Kemudian, gunakan dalam file CMake Anda:

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

Konsep utama

Konsep utama bersama meliputi Azure::Core :

  • Menangani data streaming dan input/output (I/O) melalui BodyStream bersama dengan jenis turunannya.
  • Mengakses detail respons HTTP untuk model yang dikembalikan dari operasi klien SDK apa pun, melalui Response<T>.
  • Polling operasi jangka panjang (LMO), melalui Operation<T>.
  • Pengecualian untuk melaporkan kesalahan dari permintaan layanan secara konsisten melalui jenis RequestFailedExceptionpengecualian dasar .
  • Abstraksi untuk kredensial Azure SDK (TokenCredential).
  • Lapisan transportasi HTTP yang dapat diganti untuk mengirim permintaan dan menerima respons melalui jaringan.
  • Alur HTTP dan kebijakan HTTP seperti coba lagi dan pengelogan, yang dapat dikonfigurasi melalui opsi spesifik klien layanan.

Operasi yang Berlangsung Lama

Beberapa operasi membutuhkan waktu lama untuk menyelesaikan dan memerlukan polling untuk statusnya. Metode yang memulai jenis pengembalian Operation<T> operasi yang berjalan lama.

Anda dapat secara terputus-putus melakukan polling apakah operasi telah selesai dengan menggunakan Poll() metode pada yang dikembalikan Operation<T> dan melacak kemajuan operasi menggunakan Value(). Atau, jika Anda hanya ingin menunggu sampai operasi selesai, Anda dapat menggunakan 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();

Adaptor Transportasi HTTP

Di luar kotak, Azure SDK untuk C++ mendukung pustaka libcurl dan WinHTTP sebagai tumpukan HTTP untuk berkomunikasi dengan layanan Azure melalui jaringan. SDK juga menyediakan mekanisme untuk customer-implementedadaptor transportasi HTTP. Anda dapat mempelajari lebih lanjut tentang adaptor transportasi di dokumen ini.

Troubleshooting

Tiga cara utama untuk memecahkan masalah kegagalan adalah:

  • Memeriksa pengecualian
  • Mengaktifkan pengelogan (lihat Pesan Log SDK)

Pesan Log SDK

Cara paling sederhana untuk mengaktifkan log adalah dengan mengatur variabel lingkungan AZURE_LOG_LEVEL ke salah satu nilai: |AZURE_LOG_LEVEL|Azure::Core::Diagnostics::Logger::Level|Tingkat pesan log| |-|-|-| |4, atau error, atau err|Error|Tingkat pengelogan untuk kegagalan yang tidak mungkin dipulihkan aplikasi.| |3, atau warning, atau warn|Warning|Tingkat pengelogan saat fungsi gagal melakukan tugas yang dimaksudkan.| |2, atau informational, atau information, atau info|Informational|Tingkat pengelogan saat fungsi beroperasi secara normal.| |1, atau verbose, atau debug|Verbose|Tingkat pengelogan untuk skenario pemecahan masalah terperinci.|

Kemudian, pesan log akan dicetak ke konsol (stderr). Perhatikan bahwa stderr pesan dapat diarahkan ke dalam file log seperti ini:

Pada Windows:

myprogram.exe 2> log.txt

Di Linux atau macOS:

./myprogram 2> log.txt

Selain itu, pesan log dapat diproses secara terprogram dengan menyediakan fungsi panggilan balik, yang dapat menyimpannya ke file, atau menampilkannya dengan cara kustom yang diinginkan.

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

Perhatikan, panggilan balik pendengar dijalankan pada utas yang sama dengan operasi yang memicu pesan log. Disarankan implementasi karena jumlah minimal pemrosesan pesan log pada utas panggilan balik. Jika pemrosesan pesan diperlukan, pertimbangkan untuk menerapkan dengan cara agar panggilan balik mendorong string pesan ke dalam antrean aman utas, sehingga utas lain akan memilih pesan dari antrean tersebut dan menanganinya.

Langkah selanjutnya

Jelajahi dan instal pustaka Azure SDK yang tersedia.

Contributing

Untuk detail tentang berkontribusi pada repositori ini, lihat panduan berkontribusi.

Proyek ini menyambut kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi Perjanjian Lisensi Kontributor.

Saat Anda mengirimkan permintaan pull, cla-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Kode Etik atau hubungi opencode@microsoft.com dengan pertanyaan atau komentar tambahan apa pun.

Banyak orang di seluruh dunia telah membantu membuat proyek ini lebih baik. Anda akan ingin memeriksa:

Melaporkan masalah keamanan dan bug keamanan

Masalah keamanan dan bug harus dilaporkan secara privat, melalui email, ke Microsoft Security Response Center (MSRC) secure@microsoft.com. Anda akan menerima respons dalam waktu 24 jam. Jika karena alasan tertentu Anda tidak melakukannya, silakan tindak lanjuti melalui email untuk memastikan kami menerima pesan asli Anda. Informasi lebih lanjut, termasuk kunci MSRC PGP, dapat ditemukan di Security TechCenter.

Lisensi

Azure SDK untuk C++ dilisensikan di bawah lisensi MIT .

  • Last updated on