Freigeben über


QueueServiceClient Klasse

Ein Client für die Interaktion mit dem Warteschlangendienst auf Kontoebene.

Dieser Client bietet Vorgänge zum Abrufen und Konfigurieren der Kontoeigenschaften sowie zum Auflisten, Erstellen und Löschen von Warteschlangen innerhalb des Kontos. Bei Vorgängen im Zusammenhang mit einer bestimmten Warteschlange kann ein Client für diese Entität mithilfe der get_queue_client -Funktion abgerufen werden.

Weitere optionale Konfigurationen finden Sie hier.

Vererbung
azure.storage.queue._shared.base_client.StorageAccountHostsMixin
QueueServiceClient
azure.storage.queue._encryption.StorageEncryptionMixin
QueueServiceClient

Konstruktor

QueueServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

Parameter

account_url
str
Erforderlich

Die URL des Warteschlangendienstendpunkts. Alle anderen Entitäten, die im URL-Pfad enthalten sind (z. B. Warteschlange), werden verworfen. Diese URL kann optional mit einem SAS-Token authentifiziert werden.

credential
Standardwert: None

Die Anmeldeinformationen, mit denen die Authentifizierung erfolgt. Dies ist optional, wenn die Konto-URL bereits über ein SAS-Token verfügt. Der Wert kann eine SAS-Tokenzeichenfolge, ein instance einer AzureSasCredential- oder AzureNamedKeyCredential-Instanz von azure.core.credentials, ein freigegebener Zugriffsschlüssel für ein Konto oder ein instance einer TokenCredentials-Klasse aus azure.identity sein. Wenn der Ressourcen-URI bereits ein SAS-Token enthält, wird dies zugunsten expliziter Anmeldeinformationen ignoriert.

  • außer im Fall von AzureSasCredential, bei dem die in Konflikt stehenden SAS-Token einen ValueError auslösen. Wenn Sie eine instance von AzureNamedKeyCredential verwenden, sollte "name" der Name des Speicherkontos und "key" der Speicherkontoschlüssel sein.
api_version
str

Die Speicher-API-Version, die für Anforderungen verwendet werden soll. Der Standardwert ist die neueste Dienstversion, die mit dem aktuellen SDK kompatibel ist. Die Einstellung auf eine ältere Version kann zu einer geringeren Featurekompatibilität führen.

secondary_hostname
str

Der Hostname des sekundären Endpunkts.

audience
str

Die Zielgruppe, die beim Anfordern von Token für die Azure Active Directory-Authentifizierung verwendet werden soll. Wirkt sich nur aus, wenn Anmeldeinformationen vom Typ TokenCredential sind. Der Wert kann (Standard) oder https://.queue.core.windows.net sein https://storage.azure.com/ .

Beispiele

Erstellen des QueueServiceClient mit einer Konto-URL und Anmeldeinformationen.


   from azure.storage.queue import QueueServiceClient
   queue_service = QueueServiceClient(account_url=self.account_url, credential=self.access_key)

Erstellen des QueueServiceClient mit Azure Identity-Anmeldeinformationen


   # Get a token credential for authentication
   from azure.identity import ClientSecretCredential
   token_credential = ClientSecretCredential(
       self.active_directory_tenant_id,
       self.active_directory_application_id,
       self.active_directory_application_secret
   )

   # Instantiate a QueueServiceClient using a token credential
   from azure.storage.queue import QueueServiceClient
   queue_service = QueueServiceClient(account_url=self.account_url, credential=token_credential)

Methoden

close

Diese Methode besteht darin, die vom Client geöffneten Sockets zu schließen. Es muss nicht verwendet werden, wenn sie mit einem Kontext-Manager verwendet wird.

create_queue

Erstellt eine neue Warteschlange unter dem angegebenen Konto.

Wenn bereits eine Warteschlange mit demselben Namen vorhanden ist, schlägt der Vorgang fehl. Gibt einen Client zurück, mit dem mit der neu erstellten Warteschlange interagieren soll.

delete_queue

Löscht die angegebene Warteschlange und alle darin enthaltenen Nachrichten.

Wenn eine Warteschlange erfolgreich gelöscht wurde, wird sie sofort zum Löschen markiert und ist für Clients nicht mehr zugänglich. Die Warteschlange wird später während der automatischen Speicherbereinigung aus dem Warteschlangendienst entfernt.

Beachten Sie, dass das Löschen einer Warteschlange wahrscheinlich mindestens 40 Sekunden dauert. Wenn ein Vorgang für die Warteschlange versucht wird, während er gelöscht wurde, wird ein <xref:azure.storage.queue.HttpResponseError> ausgelöst.

from_connection_string

Erstellen Sie QueueServiceClient aus einer Verbindungszeichenfolge.

get_queue_client

Rufen Sie einen Client für die Interaktion mit der angegebenen Warteschlange ab.

Die Warteschlange muss noch nicht vorhanden sein.

get_service_properties

Ruft die Eigenschaften des Warteschlangendiensts eines Speicherkontos ab, einschließlich Azure Storage Analytics.

get_service_stats

Ruft Statistiken zur Replikation für den Warteschlangendienst ab.

Sie ist nur verfügbar, wenn die georedundante Replikation mit Lesezugriff für das Speicherkonto aktiviert ist.

Mit der georedundanten Replikation behält der Azure-Speicher Daten an zwei Standorten permanent bei. An beiden Standorten behält der Azure-Speicher mehrere fehlerfreie Replikate der Daten bei. Der Standort, an dem Sie Daten lesen, erstellen, aktualisieren oder löschen, ist der primäre Speicherkontostandort. Der primäre Standort befindet sich in der Region, die Sie zum Zeitpunkt der Erstellung eines Kontos über das klassische Azure Management-Azure-Portal ausgewählt haben, z. B. USA, Norden, Mitte. Als sekundärer Standort wird der Standort bezeichnet, an dem die Daten repliziert werden. Der sekundäre Standort wird automatisch auf Grundlage des primären Standorts ermittelt und befindet sich in einem zweiten Rechenzentrum in derselben Region wie der primäre Standort. Der schreibgeschützte Zugriff ist über den sekundären Standort verfügbar, wenn die georedundante Replikation mit Lesezugriff für das Speicherkonto aktiviert ist.

list_queues

Gibt einen Generator zurück, um die Warteschlangen unter dem angegebenen Konto aufzulisten.

Der Generator folgt den vom Dienst zurückgegebenen Fortsetzungstoken und wird beendet, wenn alle Warteschlangen zurückgegeben wurden.

set_service_properties

Legt die Eigenschaften des Warteschlangendiensts eines Speicherkontos fest, einschließlich Azure Storage Analytics.

Wenn ein Element (z. B. analytics_logging) als None belassen wird, werden die vorhandenen Einstellungen des Diensts für diese Funktionalität beibehalten.

close

Diese Methode besteht darin, die vom Client geöffneten Sockets zu schließen. Es muss nicht verwendet werden, wenn sie mit einem Kontext-Manager verwendet wird.

close()

create_queue

Erstellt eine neue Warteschlange unter dem angegebenen Konto.

Wenn bereits eine Warteschlange mit demselben Namen vorhanden ist, schlägt der Vorgang fehl. Gibt einen Client zurück, mit dem mit der neu erstellten Warteschlange interagieren soll.

create_queue(name: str, metadata: Dict[str, str] | None = None, **kwargs: Any) -> QueueClient

Parameter

name
str
Erforderlich

Der Name der zu erstellenden Warteschlange.

metadata
Dict[str, str]
Erforderlich

Ein Diktat mit name_value Paaren, die der Warteschlange als Metadaten zugeordnet werden sollen. Beispiel: {'Category': 'test'}

timeout
int

Der timeout-Parameter wird in Sekunden angegeben.

Gibt zurück

Ein QueueClient für die neu erstellte Warteschlange.

Rückgabetyp

Beispiele

Erstellen Sie eine Warteschlange im Dienst.


   queue_service.create_queue("myqueue1")

delete_queue

Löscht die angegebene Warteschlange und alle darin enthaltenen Nachrichten.

Wenn eine Warteschlange erfolgreich gelöscht wurde, wird sie sofort zum Löschen markiert und ist für Clients nicht mehr zugänglich. Die Warteschlange wird später während der automatischen Speicherbereinigung aus dem Warteschlangendienst entfernt.

Beachten Sie, dass das Löschen einer Warteschlange wahrscheinlich mindestens 40 Sekunden dauert. Wenn ein Vorgang für die Warteschlange versucht wird, während er gelöscht wurde, wird ein <xref:azure.storage.queue.HttpResponseError> ausgelöst.

delete_queue(queue: QueueProperties | str, **kwargs: Any) -> None

Parameter

queue
str oder QueueProperties
Erforderlich

Die zu löschende Warteschlange. Dies kann entweder der Name der Warteschlange oder ein instance von QueueProperties sein.

timeout
int

Der timeout-Parameter wird in Sekunden angegeben.

Rückgabetyp

Beispiele

Löschen Sie eine Warteschlange im Dienst.


   queue_service.delete_queue("myqueue1")

from_connection_string

Erstellen Sie QueueServiceClient aus einer Verbindungszeichenfolge.

from_connection_string(conn_str: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parameter

conn_str
str
Erforderlich

Ein Verbindungszeichenfolge zu einem Azure Storage-Konto.

credential
Standardwert: None

Die Anmeldeinformationen, mit denen die Authentifizierung erfolgt. Dies ist optional, wenn die Konto-URL bereits über ein SAS-Token verfügt oder die Verbindungszeichenfolge bereits freigegebene Zugriffsschlüsselwerte aufweist. Der Wert kann eine SAS-Tokenzeichenfolge, ein instance einer AzureSasCredential- oder AzureNamedKeyCredential-Instanz von azure.core.credentials, ein freigegebener Zugriffsschlüssel für ein Konto oder ein instance einer TokenCredentials-Klasse aus azure.identity sein. Die hier angegebenen Anmeldeinformationen haben Vorrang vor denen im Verbindungszeichenfolge. Wenn Sie eine instance von AzureNamedKeyCredential verwenden, sollte "name" der Name des Speicherkontos und "key" der Speicherkontoschlüssel sein.

audience
str

Die Zielgruppe, die beim Anfordern von Token für die Azure Active Directory-Authentifizierung verwendet werden soll. Wirkt sich nur aus, wenn Anmeldeinformationen vom Typ TokenCredential sind. Der Wert kann (Standard) oder https://.queue.core.windows.net sein https://storage.azure.com/ .

Gibt zurück

Ein Warteschlangendienstclient.

Rückgabetyp

Beispiele

Erstellen des QueueServiceClient mit einem Verbindungszeichenfolge.


   from azure.storage.queue import QueueServiceClient
   queue_service = QueueServiceClient.from_connection_string(conn_str=self.connection_string)

get_queue_client

Rufen Sie einen Client für die Interaktion mit der angegebenen Warteschlange ab.

Die Warteschlange muss noch nicht vorhanden sein.

get_queue_client(queue: QueueProperties | str, **kwargs: Any) -> QueueClient

Parameter

queue
str oder QueueProperties
Erforderlich

Die Warteschlange. Dies kann entweder der Name der Warteschlange oder ein instance von QueueProperties sein.

Gibt zurück

Ein QueueClient-Objekt.

Rückgabetyp

Beispiele

Rufen Sie den Warteschlangenclient ab.


   # Get the queue client to interact with a specific queue
   queue = queue_service.get_queue_client(queue="myqueue2")

get_service_properties

Ruft die Eigenschaften des Warteschlangendiensts eines Speicherkontos ab, einschließlich Azure Storage Analytics.

get_service_properties(**kwargs: Any) -> Dict[str, Any]

Parameter

timeout
int

Der timeout-Parameter wird in Sekunden angegeben.

Gibt zurück

Ein Objekt, das Warteschlangendiensteigenschaften wie Analyseprotokollierung, Stunden-/Minutenmetriken, Cors-Regeln usw. enthält.

Rückgabetyp

Beispiele

Abrufen von Warteschlangendiensteigenschaften.


   properties = queue_service.get_service_properties()

get_service_stats

Ruft Statistiken zur Replikation für den Warteschlangendienst ab.

Sie ist nur verfügbar, wenn die georedundante Replikation mit Lesezugriff für das Speicherkonto aktiviert ist.

Mit der georedundanten Replikation behält der Azure-Speicher Daten an zwei Standorten permanent bei. An beiden Standorten behält der Azure-Speicher mehrere fehlerfreie Replikate der Daten bei. Der Standort, an dem Sie Daten lesen, erstellen, aktualisieren oder löschen, ist der primäre Speicherkontostandort. Der primäre Standort befindet sich in der Region, die Sie zum Zeitpunkt der Erstellung eines Kontos über das klassische Azure Management-Azure-Portal ausgewählt haben, z. B. USA, Norden, Mitte. Als sekundärer Standort wird der Standort bezeichnet, an dem die Daten repliziert werden. Der sekundäre Standort wird automatisch auf Grundlage des primären Standorts ermittelt und befindet sich in einem zweiten Rechenzentrum in derselben Region wie der primäre Standort. Der schreibgeschützte Zugriff ist über den sekundären Standort verfügbar, wenn die georedundante Replikation mit Lesezugriff für das Speicherkonto aktiviert ist.

get_service_stats(**kwargs: Any) -> Dict[str, Any]

Parameter

timeout
int

Der timeout-Parameter wird in Sekunden angegeben.

Gibt zurück

Die Statistiken des Warteschlangendiensts

Rückgabetyp

list_queues

Gibt einen Generator zurück, um die Warteschlangen unter dem angegebenen Konto aufzulisten.

Der Generator folgt den vom Dienst zurückgegebenen Fortsetzungstoken und wird beendet, wenn alle Warteschlangen zurückgegeben wurden.

list_queues(name_starts_with: str | None = None, include_metadata: bool | None = False, **kwargs: Any) -> ItemPaged[QueueProperties]

Parameter

name_starts_with
str
Erforderlich

Filtert die Ergebnisse so, dass nur Warteschlangen zurückgegeben werden, deren Namen mit dem angegebenen Präfix beginnen.

include_metadata
bool
Erforderlich

Gibt an, dass Warteschlangenmetadaten in der Antwort zurückgegeben werden.

results_per_page
int

Die maximale Anzahl von Warteschlangennamen, die pro API-Aufruf abgerufen werden sollen. Wenn die Anforderung nicht angibt, gibt der Server bis zu 5.000 Elemente zurück.

timeout
int

Legt das serverseitige Timeout für den Vorgang in Sekunden fest. Weitere Informationen finden Sie unter https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations. Dieser Wert wird nicht auf dem Client nachverfolgt oder überprüft. Informationen zum Konfigurieren clientseitiger Netzwerktimeouts finden Sie hier. Diese Funktion kann mehrere Aufrufe an den Dienst tätigen. In diesem Fall wird der angegebene Timeoutwert auf jeden einzelnen Aufruf angewendet.

Gibt zurück

Ein iterables (automatisches Paging) von QueueProperties.

Rückgabetyp

Beispiele

Listen Sie Warteschlangen im Dienst auf.


   # List all the queues in the service
   list_queues = queue_service.list_queues()
   for queue in list_queues:
       print(queue)

   # List the queues in the service that start with the name "my"
   list_my_queues = queue_service.list_queues(name_starts_with="my")
   for queue in list_my_queues:
       print(queue)

set_service_properties

Legt die Eigenschaften des Warteschlangendiensts eines Speicherkontos fest, einschließlich Azure Storage Analytics.

Wenn ein Element (z. B. analytics_logging) als None belassen wird, werden die vorhandenen Einstellungen des Diensts für diese Funktionalität beibehalten.

set_service_properties(analytics_logging: QueueAnalyticsLogging | None = None, hour_metrics: Metrics | None = None, minute_metrics: Metrics | None = None, cors: List[CorsRule] | None = None, **kwargs: Any) -> None

Parameter

analytics_logging
QueueAnalyticsLogging
Erforderlich

Gruppiert die Logging-Einstellungen für Azure-Analysen.

hour_metrics
Metrics
Erforderlich

Die Einstellungen für Stundenmetriken bieten eine Zusammenfassung der Anforderungsstatistiken, die nach API gruppiert sind, in Stündchenaggregaten für Warteschlangen.

minute_metrics
Metrics
Erforderlich

Die Minutenmetrikeneinstellungen bieten Anforderungsstatistiken für jede Minute für Warteschlangen.

cors
Optional[List[CorsRule]]
Erforderlich

Sie können bis zu fünf CorsRule-Elemente in die Liste aufnehmen. Wenn eine leere Liste angegeben wird, werden alle CORS-Regeln gelöscht, und CORS wird für den Dienst deaktiviert.

timeout
int

Der timeout-Parameter wird in Sekunden angegeben.

Beispiele

Festlegen von Warteschlangendiensteigenschaften.


   # Create service properties
   from azure.storage.queue import QueueAnalyticsLogging, Metrics, CorsRule, RetentionPolicy

   # Create logging settings
   logging = QueueAnalyticsLogging(read=True, write=True, delete=True, retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create metrics for requests statistics
   hour_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))
   minute_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create CORS rules
   cors_rule1 = CorsRule(['www.xyz.com'], ['GET'])
   allowed_origins = ['www.xyz.com', "www.ab.com", "www.bc.com"]
   allowed_methods = ['GET', 'PUT']
   max_age_in_seconds = 500
   exposed_headers = ["x-ms-meta-data*", "x-ms-meta-source*", "x-ms-meta-abc", "x-ms-meta-bcd"]
   allowed_headers = ["x-ms-meta-data*", "x-ms-meta-target*", "x-ms-meta-xyz", "x-ms-meta-foo"]
   cors_rule2 = CorsRule(
       allowed_origins,
       allowed_methods,
       max_age_in_seconds=max_age_in_seconds,
       exposed_headers=exposed_headers,
       allowed_headers=allowed_headers
   )

   cors = [cors_rule1, cors_rule2]

   # Set the service properties
   queue_service.set_service_properties(logging, hour_metrics, minute_metrics, cors)

Attribute

api_version

Die Version der Speicher-API, die für Anforderungen verwendet wird.

Rückgabetyp

str

location_mode

Der Standortmodus, den der Client derzeit verwendet.

Standardmäßig ist dies "primär". Zu den Optionen gehören "primär" und "sekundär".

Rückgabetyp

str

primary_endpoint

Die vollständige URL des primären Endpunkts.

Rückgabetyp

str

primary_hostname

Der Hostname des primären Endpunkts.

Rückgabetyp

str

secondary_endpoint

Die vollständige sekundäre Endpunkt-URL, falls konfiguriert.

Wenn kein Wertfehler verfügbar ist, wird ein ValueError ausgelöst. Um einen sekundären Hostnamen explizit anzugeben, verwenden Sie das optionale secondary_hostname Schlüsselwort (keyword) Argument für die Instanziierung.

Rückgabetyp

str

Ausnahmen

secondary_hostname

Der Hostname des sekundären Endpunkts.

Falls nicht verfügbar, ist dies Keine. Um einen sekundären Hostnamen explizit anzugeben, verwenden Sie das optionale secondary_hostname Schlüsselwort (keyword) Argument für die Instanziierung.

Rückgabetyp

url

Die vollständige Endpunkt-URL für diese Entität, einschließlich SAS-Token, falls verwendet.

Dies kann entweder der primäre Endpunkt oder der sekundäre Endpunkt sein, abhängig vom aktuellen location_mode. :returns: Die vollständige Endpunkt-URL für diese Entität, einschließlich SAS-Token, falls verwendet. :rtype: str