Pustaka klien bersama Azure Core untuk Python - versi 1.29.6

Artikel
12/16/2023

Inti Azure menyediakan pengecualian dan modul bersama untuk pustaka klien Python SDK. Pustaka ini mengikuti Panduan Desain Azure SDK untuk Python .

Jika Anda adalah pengembang pustaka klien, silakan referensikan referensi pengembang pustaka klien untuk informasi lebih lanjut.

Kode sumber | Paket (Pypi) | Paket (Conda) | Dokumentasi referensi API

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi dan pertanyaan lebih lanjut, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Biasanya, Anda tidak perlu menginstal inti azure; ini akan diinstal ketika Anda menginstal salah satu pustaka klien menggunakannya. Jika Anda ingin menginstalnya secara eksplisit (untuk mengimplementasikan pustaka klien Anda sendiri, misalnya), Anda dapat menemukannya di sini.

Konsep utama

Pengecualian Pustaka Inti Azure

AzureError

AzureError adalah pengecualian dasar untuk semua kesalahan.

class AzureError(Exception):
    def __init__(self, message, *args, **kwargs):
        self.inner_exception = kwargs.get("error")
        self.exc_type, self.exc_value, self.exc_traceback = sys.exc_info()
        self.exc_type = self.exc_type.__name__ if self.exc_type else type(self.inner_exception)
        self.exc_msg = "{}, {}: {}".format(message, self.exc_type, self.exc_value)  # type: ignore
        self.message = str(message)
        self.continuation_token = kwargs.get("continuation_token")
        super(AzureError, self).__init__(self.message, *args)

pesan adalah pesan apa pun (str) yang akan dikaitkan dengan pengecualian.

args adalah args tambahan untuk disertakan dengan pengecualian.

kwarg adalah argumen kata kunci untuk disertakan dengan pengecualian. Gunakan kesalahan kata kunci untuk meneruskan pengecualian internal dan continuation_token referensi token untuk melanjutkan operasi yang tidak lengkap.

Pengecualian berikut mewarisi dari AzureError:

ServiceRequestError

Terjadi kesalahan saat mencoba membuat permintaan ke layanan. Tidak ada permintaan yang dikirim.

ServiceResponseError

Permintaan dikirim, tetapi klien gagal memahami respons. Koneksi mungkin telah kehabisan waktu. Kesalahan ini dapat dicoba kembali untuk operasi yang idempotensi atau aman.

HttpResponseError

Permintaan dibuat, dan kode status tidak berhasil diterima dari layanan.

class HttpResponseError(AzureError):
    def __init__(self, message=None, response=None, **kwargs):
        self.reason = None
        self.response = response
        if response:
            self.reason = response.reason
            self.status_code = response.status_code
        self.error = self._parse_odata_body(ODataV4Format, response)  # type: Optional[ODataV4Format]
        if self.error:
            message = str(self.error)
        else:
            message = message or "Operation returned an invalid status '{}'".format(
                self.reason
            )

        super(HttpResponseError, self).__init__(message=message, **kwargs)

pesan adalah pesan kesalahan respons HTTP (opsional)

respons adalah respons HTTP (opsional).

kwarg adalah argumen kata kunci untuk disertakan dengan pengecualian.

Pengecualian berikut mewarisi dari HttpResponseError:

DecodeError

Kesalahan yang dimunculkan selama deserialisasi respons.

IncompleteReadError

Kesalahan yang dimunculkan jika peer menutup koneksi sebelum kami menerima isi pesan lengkap.

ResourceExistsError

Respons kesalahan dengan kode status 4xx. Ini tidak akan dinaikkan langsung oleh alur inti Azure.

ResourceNotFoundError

Respons kesalahan, biasanya dipicu oleh respons 412 (untuk pembaruan) atau 404 (untuk get/post).

ResourceModifiedError

Respons kesalahan dengan kode status 4xx, biasanya Konflik 412. Ini tidak akan dinaikkan langsung oleh alur inti Azure.

ResourceNotModifiedError

Respons kesalahan dengan kode status 304. Ini tidak akan dinaikkan langsung oleh alur inti Azure.

ClientAuthenticationError

Respons kesalahan dengan kode status 4xx. Ini tidak akan dinaikkan langsung oleh alur inti Azure.

TooManyRedirectsError

Kesalahan muncul ketika jumlah maksimum upaya pengalihan tercapai. Jumlah maksimum pengalihan dapat dikonfigurasi dalam RedirectPolicy.

class TooManyRedirectsError(HttpResponseError):
    def __init__(self, history, *args, **kwargs):
        self.history = history
        message = "Reached maximum redirect attempts."
        super(TooManyRedirectsError, self).__init__(message, *args, **kwargs)

riwayat digunakan untuk mencakup permintaan/respons yang mengakibatkan permintaan yang dialihkan.

args adalah args tambahan untuk disertakan dengan pengecualian.

kwarg adalah argumen kata kunci untuk disertakan dengan pengecualian.

StreamConsumedError

Kesalahan muncul jika Anda mencoba mengakses aliran azure.core.rest.HttpResponse atau azure.core.rest.AsyncHttpResponse setelah aliran respons dikonsumsi.

StreamClosedError

Kesalahan muncul jika Anda mencoba mengakses aliran azure.core.rest.HttpResponse atau azure.core.rest.AsyncHttpResponse setelah aliran respons ditutup.

ResponseNotReadError

Kesalahan muncul jika Anda mencoba mengakses content dari azure.core.rest.HttpResponse atau azure.core.rest.AsyncHttpResponse sebelum membaca byte respons terlebih dahulu.

Konfigurasi

Saat memanggil metode, beberapa properti dapat dikonfigurasi dengan meneruskan sebagai argumen kwargs.

Parameter	Deskripsi
header	Header Permintaan HTTP.
request_id	Id permintaan yang akan ditambahkan ke header.
user_agent	Jika ditentukan, ini akan ditambahkan di depan string agen pengguna.
logging_enable	Gunakan untuk mengaktifkan per operasi. Default ke `False`.
pencatat	Jika ditentukan, itu akan digunakan untuk mencatat informasi.
response_encoding	Pengodean yang akan digunakan jika diketahui untuk layanan ini (akan menonaktifkan deteksi otomatis).
proksi	Memetakan protokol atau protokol dan nama host ke URL proksi.
raw_request_hook	Fungsi panggilan balik. Akan dipanggil berdasarkan permintaan.
raw_response_hook	Fungsi panggilan balik. Akan dipanggil pada respons.
network_span_namer	Dapat dipanggil untuk menyesuaikan nama rentang.
tracing_attributes	Atribut yang akan diatur pada semua rentang yang dibuat.
permit_redirects	Apakah klien mengizinkan pengalihan. Default ke `True`.
redirect_max	Pengalihan maksimum yang diizinkan. Default ke `30`.
retry_total	Jumlah total percobaan ulang yang diizinkan. Lebih diutamakan daripada hitungan lain. Nilai defaultnya adalah `10`.
retry_connect	Berapa banyak kesalahan terkait koneksi yang akan diulang. Ini adalah kesalahan yang diajukan sebelum permintaan dikirim ke server jarak jauh, yang kami asumsikan belum memicu server untuk memproses permintaan. Nilai defaultnya adalah `3`.
retry_read	Berapa kali untuk mencoba kembali kesalahan baca. Kesalahan ini dimunculkan setelah permintaan dikirim ke server, sehingga permintaan mungkin memiliki efek samping. Nilai defaultnya adalah `3`.
retry_status	Berapa kali untuk mencoba kembali kode status yang buruk. Nilai defaultnya adalah `3`.
retry_backoff_factor	Faktor backoff untuk diterapkan di antara upaya setelah percobaan kedua (sebagian besar kesalahan segera diselesaikan dengan percobaan kedua tanpa penundaan). Kebijakan coba lagi akan tidur selama: `{backoff factor} * (2 ** ({number of total retries} - 1))` detik. Jika backoff_factor adalah 0,1, maka coba lagi akan tidur selama [0.0s, 0.2s, 0.4s, ...] di antara percobaan ulang. Nilai defaultnya adalah `0.8`.
retry_backoff_max	Waktu back off maksimum. Nilai defaultnya adalah `120` detik (2 menit).
retry_mode	Penundaan tetap atau eksponensial antara upaya, defaultnya adalah `Exponential`.
waktu habis	Pengaturan batas waktu untuk operasi dalam detik, defaultnya adalah `604800`s (7 hari).
connection_timeout	Satu float dalam hitungan detik untuk batas waktu koneksi. Default ke `300` detik.
read_timeout	Satu float dalam detik untuk batas waktu baca. Default ke `300` detik.
connection_verify	Verifikasi sertifikat SSL. Diaktifkan secara default. Atur ke False untuk menonaktifkan, atau dapat diatur ke jalur ke file atau direktori CA_BUNDLE dengan sertifikat CA tepercaya.
connection_cert	Sertifikat sisi klien. Anda dapat menentukan sertifikasi lokal untuk digunakan sebagai sertifikat sisi klien, sebagai satu file (berisi kunci privat dan sertifikat) atau sebagai tupel dari kedua jalur file.
proksi	Protokol atau protokol pemetaan kamus dan nama host ke URL proksi.
cookie	Objek Dict atau CookieJar untuk dikirim dengan `Request`.
connection_data_block_size	Ukuran blok data yang dikirim melalui koneksi. Default ke `4096` byte.

Transportasi asinkron

Transportasi asinkron dirancang untuk ikut serta. AioHttp adalah salah satu implementasi transportasi asinkron yang didukung. Ini tidak diinstal secara default. Anda perlu menginstalnya secara terpisah.

Modul bersama

MatchConditions

MatchConditions adalah enum untuk menjelaskan kondisi kecocokan.

class MatchConditions(Enum):
    Unconditionally = 1  # Matches any condition
    IfNotModified = 2  # If the target object is not modified. Usually it maps to etag=<specific etag>
    IfModified = 3  # Only if the target object is modified. Usually it maps to etag!=<specific etag>
    IfPresent = 4   # If the target object exists. Usually it maps to etag='*'
    IfMissing = 5   # If the target object does not exist. Usually it maps to etag!='*'

CaseInsensitiveEnumMeta

Metaclass untuk mendukung enum yang tidak peka huruf besar/kecil.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

class MyCustomEnum(str, Enum, metaclass=CaseInsensitiveEnumMeta):
    FOO = 'foo'
    BAR = 'bar'

Nilai Sentinel Null

Objek sentinel falsy yang seharusnya digunakan untuk menentukan atribut tanpa data. Ini akan diserialisasikan ke null pada kawat.

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Berkontribusi

Proyek ini menyambut baik 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 https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, 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 repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat FAQ Kode Etik atau hubungi opencode@microsoft.com untuk mengajukan pertanyaan atau komentar tambahan.

Share via