Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Zestaw Azure SDK dla języka Python składa się z wielu niezależnych bibliotek, które są wymienione w indeksie pakietów zestawu SDK języka Python.
Wszystkie biblioteki mają pewne typowe cechy i wzorce użycia, takie jak instalacja i użycie wbudowanego kodu JSON dla argumentów obiektów.
Konfigurowanie lokalnego środowiska projektowego
Jeśli jeszcze tego nie zrobiono, możesz skonfigurować środowisko, w którym można uruchomić ten kod. Oto kilka opcji:
Skonfiguruj środowisko wirtualne języka Python przy użyciu
venvlub wybranego narzędzia. Aby rozpocząć korzystanie ze środowiska wirtualnego, pamiętaj, aby go aktywować. Aby zainstalować język Python, zobacz Instalowanie języka Python.#!/bin/bash # Create a virtual environment python -m venv .venv # Activate the virtual environment source .venv/Scripts/activate # only required for Windows (Git Bash)Użyj środowiska Conda. Aby zainstalować aplikację Conda, zobacz Instalowanie narzędzia Miniconda.
Użyj kontenera deweloperskiego w Visual Studio Code lub GitHub Codespaces.
Instalacja biblioteki
Wybierz metodę instalacji odpowiadającą narzędziu do zarządzania środowiskiem Python, pip lub conda.
Aby zainstalować określony pakiet biblioteki, użyj polecenia pip install:
REM Install the management library for Azure Storage
pip install azure-mgmt-storage
REM Install the client library for Azure Blob Storage
pip install azure-storage-blob
REM Install the azure identity library for Azure authentication
pip install azure-identity
pip install pobiera najnowszą wersję biblioteki w bieżącym środowisku języka Python.
Można również użyć pip, aby odinstalować biblioteki i zainstalować określone wersje, w tym wersje zapoznawcze. Aby uzyskać więcej informacji, zobacz How to install Azure library packages for Python (Jak zainstalować pakiety bibliotek platformy Azure dla języka Python).
Operacje asynchroniczne
Biblioteki asynchroniczne
Wiele bibliotek klienckich i zarządczych udostępnia wersje asynchroniczne (.aio). Biblioteka asyncio jest dostępna od wersji 3.4 języka Python, a słowa kluczowe async/await zostały wprowadzone w języku Python 3.5. Wersje asynchroniczne bibliotek mają być używane z językiem Python 3.5 lub nowszym.
Przykłady bibliotek zestawu AZURE Python SDK z wersjami asynchronizowanymi to azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio i azure.mgmt.compute.aio.
Te biblioteki wymagają transportu asynchronicznego, takiego jak aiohttp, aby działać. Biblioteka azure-core udostępnia transport asynchroniczny , AioHttpTransportktóry jest używany przez biblioteki asynchroniczne, więc może nie być konieczne oddzielne zainstalowanie aiohttp .
Poniższy kod pokazuje, jak utworzyć plik python, który pokazuje, jak utworzyć klienta dla asynchronicznych wersji biblioteki usługi Azure Blob Storage:
credential = DefaultAzureCredential()
async def run():
async with BlobClient(
storage_url,
container_name="blob-container-01",
blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
credential=credential,
) as blob_client:
# Open a local file and upload its contents to Blob Storage
with open("./sample-source.txt", "rb") as data:
await blob_client.upload_blob(data)
print(f"Uploaded sample-source.txt to {blob_client.url}")
# Close credential
await credential.close()
asyncio.run(run())
Pełny przykład znajduje się w witrynie GitHub w use_blob_auth_async.py. Aby uzyskać synchroniczną wersję tego kodu, odwołaj się do Przykład: przesyłanie obiektu blob.
Długotrwałe operacje
Niektóre operacje zarządzania, które wywołujesz (takie jak ComputeManagementClient.virtual_machines.begin_create_or_update i WebAppsClient.web_apps.begin_create_or_update), zwracają narzędzie do monitorowania dla długotrwałych operacji, LROPoller[<type>], gdzie <type> jest specyficzne dla danej operacji.
Uwaga / Notatka
Możesz zauważyć różnice w nazwach metod w bibliotece w zależności od jej wersji i tego, czy jest oparta na azure.core. Starsze biblioteki, które nie są oparte na pliku azure.core, zwykle używają nazw, takich jak create_or_update. Biblioteki oparte na azure.core dodają prefiks begin_ do nazw metod, aby lepiej wskazać, że są to operacje długiego sondowania. Migrowanie starego kodu do nowszej biblioteki azure.core zwykle oznacza dodanie prefiksu begin_ do nazw metod, ponieważ większość podpisów metod pozostaje taka sama.
Zwracany LROPoller typ oznacza, że operacja jest asynchroniczna. W związku z tym należy wywołać metodę pollera result , aby poczekać na zakończenie operacji i uzyskać jej wynik.
Poniższy kod pobrany z przykładu: Tworzenie i wdrażanie aplikacji internetowej przedstawia przykład użycia narzędzia poller do oczekiwania na wynik:
# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.
poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,
WEB_APP_NAME,
{
"location": LOCATION,
"server_farm_id": plan_result.id,
"site_config": {
"linux_fx_version": "python|3.8"
}
}
)
web_app_result = poller.result()
W tym przypadku zwracana wartość begin_create_or_update jest typu AzureOperationPoller[Site], co oznacza, że zwracana wartość poller.result() jest obiektem Site.
Wyjątki
Ogólnie rzecz biorąc, biblioteki platformy Azure zgłaszają wyjątki, gdy operacje nie działają zgodnie z oczekiwaniami, w tym żądania HTTP, które zakończyły się niepowodzeniem, do interfejsu API REST platformy Azure. W przypadku kodu aplikacji można używać bloków try...except wokół operacji bibliotecznych.
Aby uzyskać więcej informacji na temat typu wyjątków, które mogą zostać zgłoszone, zobacz dokumentację dotyczącą danej operacji.
Przemysł drzewny
Najnowsze biblioteki platformy Azure używają standardowej biblioteki języka Python logging do generowania danych wyjściowych dziennika. Poziom rejestrowania można ustawić dla poszczególnych bibliotek, grup bibliotek lub wszystkich bibliotek. Po zarejestrowaniu procedury obsługi strumienia rejestrowania można włączyć rejestrowanie dla określonego obiektu klienta lub określonej operacji. Aby uzyskać więcej informacji, zobacz Rejestrowanie w bibliotekach platformy Azure.
Konfiguracja serwera proxy
Aby określić serwer proxy, możesz użyć zmiennych środowiskowych lub opcjonalnych argumentów. Aby uzyskać więcej informacji, zobacz Jak skonfigurować serwery proxy.
Opcjonalne argumenty dla obiektów i metod klienta
W dokumentacji referencyjnej biblioteki często widać argument **kwargs lub **operation_config w sygnaturze konstruktora obiektu klienta lub określonej metody operacyjnej. Te symbole zastępcze wskazują, że dany obiekt lub metoda może obsługiwać inne nazwane argumenty. Zazwyczaj dokumentacja referencyjna wskazuje konkretne argumenty, których można użyć. Istnieją również pewne ogólne argumenty, które są często popierane, jak opisano w poniższych sekcjach.
Argumenty dla bibliotek opartych na azure.core
Te argumenty dotyczą tych bibliotek wymienionych w języku Python — nowe biblioteki. Na przykład poniżej przedstawiono podzbiór argumentów słów kluczowych dla elementu azure-core. Aby uzyskać pełną listę, zobacz plik README usługi GitHub dla platformy azure-core.
| Nazwa | Typ | Wartość domyślna | Opis |
|---|---|---|---|
| włączanie rejestrowania | Boolean | Nieprawda | Włącza rejestrowanie. Aby uzyskać więcej informacji, zobacz Rejestrowanie w bibliotekach platformy Azure. |
| Proxies | słownik | {} | Adresy URL serwera proxy. Aby uzyskać więcej informacji, zobacz Jak skonfigurować serwery proxy. |
| użyj_ustawień_środowiska | Boolean | Prawda | Jeśli to prawda, umożliwia używanie zmiennych środowiskowych HTTP_PROXY i HTTPS_PROXY dla serwerów proxy. Jeśli wartość False, zmienne środowiskowe są ignorowane. Aby uzyskać więcej informacji, zobacz Jak skonfigurować serwery proxy. |
| czas_oczekiwania_na_połączenie | int (integer) | 300 | Limit czasu w sekundach na nawiązywanie połączenia z punktami końcowymi interfejsu API REST platformy Azure. |
| czas oczekiwania na odczyt | int (integer) | 300 | Limit czasu w sekundach na ukończenie operacji interfejsu API REST platformy Azure (czyli oczekiwanie na odpowiedź). |
| Ponów całkowity | int (integer) | 10 | Liczba dozwolonych ponownych prób wywołań interfejsu API REST. Użyj polecenia retry_total=0 , aby wyłączyć ponawianie prób. |
| tryb ponawiania | wyliczenie | wykładniczy | Stosuje harmonogram ponawiania prób w sposób liniowy lub wykładniczy. W przypadku wartości "single" ponowne próby są wykonywane w regularnych odstępach czasu. Jeśli ustawiono jako "wykładnicza", każda kolejna próba będzie czekać dwa razy dłużej niż poprzednia. |
Poszczególne biblioteki nie są zobowiązane do obsługi żadnego z tych argumentów, dlatego zawsze zapoznaj się z dokumentacją referencyjną dla każdej biblioteki, aby uzyskać szczegółowe informacje. Ponadto każda biblioteka może obsługiwać inne argumenty. Na przykład w przypadku argumentów słów kluczowych specyficznych dla magazynu obiektów blob zobacz plik README na GitHubie dla azure-storage-blob.
Wzorzec wbudowanego kodu JSON dla argumentów obiektów
Wiele operacji w bibliotekach platformy Azure umożliwia wyrażenie argumentów obiektów jako obiektów dyskretnych lub jako wbudowany kod JSON.
Załóżmy na przykład, że masz ResourceManagementClient obiekt, za pomocą którego tworzysz grupę zasobów przy użyciu jej create_or_update metody. Drugim argumentem tej metody jest typ ResourceGroup.
Aby wywołać metodę create_or_update, można utworzyć oddzielne wystąpienie ResourceGroup bezpośrednio z wymaganymi argumentami (location w tym przypadku):
# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
"PythonSDKExample-rg",
ResourceGroup(location="centralus")
)
Alternatywnie można przekazać te same parametry jako JSON w jednym wierszu.
# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
"PythonAzureExample-rg", {"location": "centralus"}
)
W przypadku używania wbudowanego kodu JSON biblioteki platformy Azure automatycznie konwertują wbudowany kod JSON na odpowiedni typ obiektu dla danego argumentu.
Obiekty mogą również mieć zagnieżdżone argumenty obiektów, w tym przypadku można również użyć zagnieżdżonego kodu JSON.
Załóżmy na przykład, że masz wystąpienie KeyVaultManagementClient obiektu i wywołujesz jego create_or_update. W tym przypadku trzeci argument jest typu VaultCreateOrUpdateParameters, który sam zawiera argument typu VaultProperties.
VaultProperties, z kolei zawiera argumenty obiektów typu Sku i list[AccessPolicyEntry]. Obiekt Sku zawiera SkuName obiekt, a każdy z nich AccessPolicyEntry zawiera Permissions obiekt.
Aby wywołać begin_create_or_update z obiektami osadzonymi, należy użyć kodu podobnego do poniższego (zakładając, że tenant_id, object_id i LOCATION są już zdefiniowane). Można również utworzyć niezbędne obiekty przed wywołaniem funkcji.
# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
RESOURCE_GROUP_NAME,
KEY_VAULT_NAME_A,
VaultCreateOrUpdateParameters(
location = LOCATION,
properties = VaultProperties(
tenant_id = tenant_id,
sku = Sku(
name="standard",
family="A"
),
access_policies = [
AccessPolicyEntry(
tenant_id = tenant_id,
object_id = object_id,
permissions = Permissions(
keys = ['all'],
secrets = ['all']
)
)
]
)
)
)
key_vault1 = poller.result()
To samo wywołanie przy użyciu wbudowanego kodu JSON jest wyświetlane w następujący sposób:
# Provision a Key Vault using inline JSON
poller = keyvault_client.vaults.begin_create_or_update(
RESOURCE_GROUP_NAME,
KEY_VAULT_NAME_B,
{
'location': LOCATION,
'properties': {
'sku': {
'name': 'standard',
'family': 'A'
},
'tenant_id': tenant_id,
'access_policies': [{
'tenant_id': tenant_id,
'object_id': object_id,
'permissions': {
'keys': ['all'],
'secrets': ['all']
}
}]
}
}
)
key_vault2 = poller.result()
Ponieważ obie formy są równoważne, możesz wybrać dowolną preferowaną, a nawet przeplatać je. (Pełny kod tych przykładów można znaleźć w witrynie GitHub).
Jeśli kod JSON nie jest poprawnie sformułowany, zazwyczaj występuje błąd "DeserializationError: Nie można deserializować obiektu: type, AttributeError: "str" nie ma atrybutu "get". Częstą przyczyną tego błędu jest podanie pojedynczego ciągu dla właściwości, gdy biblioteka oczekuje zagnieżdżonego obiektu JSON. Na przykład użycie 'sku': 'standard' w poprzednim przykładzie generuje błąd, ponieważ parametr sku jest obiektem Sku, który oczekuje wbudowanego obiektu JSON. W tym przypadku {'name': 'standard'} mapuje na oczekiwany typ SkuName.
Dalsze kroki
Teraz, gdy znasz typowe wzorce korzystania z bibliotek platformy Azure dla języka Python, zapoznaj się z poniższymi autonomicznymi przykładami, aby zapoznać się z konkretnymi scenariuszami zarządzania i biblioteki klienta. Możesz wypróbować te przykłady w dowolnej kolejności, ponieważ nie są one sekwencyjne ani współzależne.