Gambaran umum pemecahan masalah untuk Azure SDK untuk Java

Artikel
12/14/2023

Artikel ini memperkenalkan banyak alat pemecahan masalah yang tersedia untuk Anda saat Anda menggunakan Azure SDK untuk Java, dan menautkan ke artikel lain dengan detail lebih lanjut.

Azure SDK untuk Java terdiri dari banyak pustaka klien - satu atau beberapa untuk setiap Layanan Azure yang ada. Kami memastikan bahwa semua pustaka klien dibangun ke standar yang konsisten dan tinggi, dengan pola umum untuk konfigurasi, pengelogan, penanganan pengecualian, dan pemecahan masalah. Untuk informasi selengkapnya, lihat Menggunakan Azure SDK untuk Java.

Karena pemecahan masalah dapat mencakup area subjek yang begitu luas, kami telah mengembangkan panduan pemecahan masalah berikut yang mungkin ingin Anda tinjau:

Memecahkan masalah autentikasi Azure Identity mencakup teknik investigasi kegagalan autentikasi, kesalahan umum untuk jenis kredensial di pustaka klien Azure Identity Java, dan langkah-langkah mitigasi untuk mengatasi kesalahan ini.
Memecahkan masalah konflik versi dependensi mencakup subjek yang terkait dengan diagnosis, mitigasi, dan meminimalkan konflik dependensi. Konflik ini dapat muncul saat Anda menggunakan pustaka klien Azure SDK for Java dalam sistem yang dibangun dengan alat seperti Maven dan Gradle.
Memecahkan masalah jaringan mencakup subjek yang terkait dengan penelusuran kesalahan HTTP di luar pustaka klien, menggunakan alat seperti Fiddler dan Wireshark.

Bersama dengan panduan pemecahan masalah umum ini, kami juga menyediakan panduan pemecahan masalah khusus pustaka. Saat ini, panduan berikut tersedia:

Di luar dokumen-dokumen ini, konten berikut memberikan panduan tentang membuat penggunaan terbaik dari penanganan pengelogan dan pengecualian karena berkaitan dengan Azure SDK untuk Java.

Menggunakan pengelogan di Azure SDK untuk Java

Bagian berikut menjelaskan cara mengaktifkan berbagai jenis pengelogan.

Mengaktifkan pengelogan klien

Untuk memecahkan masalah, penting untuk terlebih dahulu mengaktifkan pengelogan untuk memantau perilaku aplikasi Anda. Kesalahan dan peringatan dalam log umumnya memberikan wawasan yang berguna tentang apa yang salah dan terkadang menyertakan tindakan korektif untuk memperbaiki masalah. Azure SDK untuk Java memiliki dukungan pengelogan yang komprehensif. Untuk informasi selengkapnya, lihat Mengonfigurasi pengelogan di SDK Azure untuk Java.

Mengaktifkan pengelogan permintaan/respons HTTP

Saat memecahkan masalah, berguna untuk meninjau permintaan HTTP saat dikirim dan diterima antara layanan Azure. Untuk mengaktifkan pengelogan permintaan HTTP dan payload respons, Anda dapat mengonfigurasi hampir semua pustaka klien Azure SDK for Java di penyusun klien mereka seperti yang ditunjukkan dalam contoh berikut. Secara khusus, beri perhatian khusus pada httpLogOptions metode pada penyusun klien, dan nilai enum yang tersedia di HttpLogDetailLevel.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .connectionString(connectionString)
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

Kode ini mengubah pengelogan permintaan/respons HTTP untuk satu instans klien. Atau, Anda dapat mengonfigurasi permintaan dan respons HTTP pengelogan untuk seluruh aplikasi Anda dengan mengatur AZURE_HTTP_LOG_DETAIL_LEVEL variabel lingkungan ke salah satu nilai dalam tabel berikut. Penting untuk dicatat bahwa perubahan ini memungkinkan pengelogan untuk setiap klien Azure yang mendukung pengelogan permintaan/respons HTTP.

Value	Tingkat pengelogan
`none`	Pengelogan permintaan/respons HTTP dinonaktifkan.
`basic`	Hanya mencatat URL, metode HTTP, dan waktu untuk menyelesaikan permintaan.
`headers`	Mencatat semuanya di BASIC, ditambah semua header permintaan dan respons.
`body`	Mencatat semua yang ada di BASIC, ditambah semua isi permintaan dan respons.
`body_and_headers`	Mencatat semua yang ada di HEADERS dan BODY.

Catatan

Saat Anda mencatat badan permintaan dan respons, pastikan bahwa mereka tidak berisi informasi rahasia. Saat Anda mencatat parameter dan header kueri, pustaka klien memiliki sekumpulan parameter dan header kueri default yang dianggap aman untuk dicatat. Dimungkinkan untuk menambahkan parameter dan header kueri tambahan yang aman untuk dicatat, seperti yang diperlihatkan dalam contoh berikut:

clientBuilder.httpLogOptions(new HttpLogOptions()
    .addAllowedHeaderName("safe-to-log-header-name")
    .addAllowedQueryParamName("safe-to-log-query-parameter-name"))

Penanganan pengecualian di Azure SDK untuk Java

Sebagian besar metode layanan klien Azure SDK untuk Java melempar HttpResponseException atau subkelas yang lebih spesifik pada kegagalan. Jenis ini HttpResponseException mencakup objek kesalahan respons terperinci yang memberikan wawasan khusus yang berguna tentang apa yang salah dan menyertakan tindakan korektif untuk memperbaiki masalah umum. Anda dapat menemukan informasi kesalahan ini di dalam properti HttpResponseException pesan objek. Karena pengecualian ini adalah pengecualian runtime, dokumentasi referensi JavaDoc tidak secara eksplisit memanggilnya.

Contoh berikut menunjukkan kepada Anda cara menangkap pengecualian ini dengan klien sinkron:

try {
    ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
    client.getConfigurationSetting(setting);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

Dengan klien asinkron, Anda dapat menangkap dan menangani pengecualian dalam panggilan balik kesalahan, seperti yang ditunjukkan dalam contoh berikut:

ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
asyncClient.getConfigurationSetting(setting)
    .doOnSuccess(ignored -> System.out.println("Success!"))
    .doOnError(
        error -> error instanceof ResourceNotFoundException,
        error -> System.out.println("Exception: 'getConfigurationSetting' could not be performed."));

Menggunakan pelacakan di Azure SDK untuk Java

Azure SDK for Java menawarkan dukungan pelacakan yang komprehensif, memungkinkan Anda melihat alur eksekusi melalui kode aplikasi dan pustaka klien yang Anda gunakan. Anda dapat mengaktifkan pelacakan di pustaka klien Azure dengan menggunakan dan mengonfigurasi SDK OpenTelemetry atau dengan menggunakan agen yang kompatibel dengan OpenTelemetry. OpenTelemetry adalah kerangka pengamatan sumber terbuka yang populer untuk menghasilkan, menangkap, dan mengumpulkan data telemetri untuk perangkat lunak cloud-native.

Untuk informasi selengkapnya tentang cara mengaktifkan pelacakan di Azure SDK untuk Java, lihat Mengonfigurasi pelacakan di Azure SDK untuk Java.

Langkah berikutnya

Jika panduan pemecahan masalah dalam artikel ini tidak membantu mengatasi masalah saat Anda menggunakan pustaka klien Azure SDK untuk Java, kami sarankan Anda mengajukan masalah di repositori Azure SDK for Java GitHub.

Bagikan melalui