QueueServiceClient 類別

參考

在帳戶層級與佇列服務互動的用戶端。

此用戶端提供作業來擷取和設定帳戶屬性，以及列出、建立和刪除帳戶內的佇列。對於與特定佇列相關的作業，可以使用函式擷取此實體的 get_queue_client 用戶端。

如需更多選擇性設定，請按一下這裡。

繼承: azure.storage.queue._shared.base_client.StorageAccountHostsMixin

QueueServiceClient

azure.storage.queue._encryption.StorageEncryptionMixin

QueueServiceClient

建構函式

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

參數

account_url: str

必要

佇列服務端點的 URL。 URL 路徑中包含的任何其他實體 (例如，將會捨棄佇列) 。此 URL 可以選擇性地使用 SAS 權杖進行驗證。

credential

預設值: None

要用來驗證的認證。如果帳戶 URL 已經有 SAS 權杖，則這是選擇性的。此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。如果資源 URI 已經包含 SAS 權杖，則會忽略此權杖，以使用明確的認證

除了 AzureSasCredential 的情況之外，衝突的 SAS 權杖將會引發 ValueError。如果使用 AzureNamedKeyCredential 的實例，「name」應該是儲存體帳戶名稱，而「key」應該是儲存體帳戶金鑰。

api_version: str

要用於要求的儲存體 API 版本。預設值是與目前 SDK 相容的最新服務版本。將設定為較舊版本可能會導致功能相容性降低。

secondary_hostname: str

次要端點的主機名稱。

audience: str

要求 Azure Active Directory 驗證權杖時要使用的物件。只有在認證類型為 TokenCredential 時才會生效。此值可以是 https://storage.azure.com/ 預設) 或 HTTPs：//.queue.core.windows.net (。

範例

使用帳戶 URL 和認證建立 QueueServiceClient。


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

使用 Azure 身分識別認證建立 QueueServiceClient。


   # 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)

方法

close	這個方法是關閉用戶端所開啟的通訊端。與內容管理員搭配使用時，不需要使用它。
create_queue	在指定的帳號下建立新的佇列。如果已有同名的佇列存在，作業就會失敗。傳回要與新建立佇列互動的用戶端。
delete_queue	刪除指定的佇列及其包含的任何訊息。成功刪除佇列時，它會立即標示為要刪除，而且用戶端無法再存取。稍後記憶體回收時，將會從佇列服務中移除此佇列。請注意，刪除佇列可能需要至少 40 秒才能完成。如果在刪除佇列時嘗試對佇列執行作業， <xref:azure.storage.queue.HttpResponseError> 將會擲回。
from_connection_string	從連接字串建立 QueueServiceClient。
get_queue_client	取得用戶端以與指定的佇列互動。佇列不需要已經存在。
get_service_properties	取得儲存體帳戶佇列服務的屬性，包括 Azure 儲存體分析。
get_service_stats	擷取與佇列服務的複寫相關的統計資料。只有在儲存體帳戶啟用讀取權限異地備援複寫時，才能使用。有了地理備援複寫，Azure 儲存體會以持久的方式在兩個位置維護您的資料。在這兩個位置中，Azure 儲存體會持續維護狀況良好的多個資料複本。您讀取、建立、更新或刪除資料的位置是「主要」儲存體帳戶的位置。主要位置存在於您透過 Azure 管理 Azure 傳統入口網站建立帳戶時所選擇的區域，例如美國中北部。資料複寫的目標位置是「次要」位置。次要位置是根據主要的位置自動判斷而來，它是與主要位置位於相同地區的第二個資料中心。當儲存體帳戶啟用「讀取權限的地理備援複寫」時，可從次要位置使用唯讀權限。
list_queues	傳回產生器，以列出指定帳戶下的佇列。產生器會延遲遵循服務傳回的接續權杖，並在傳回所有佇列時停止。
set_service_properties	設定儲存體帳戶佇列服務的屬性，包括 Azure 儲存體分析。如果專案 (例如，analytics_logging) 保留為 None，則會保留該服務上的現有設定。

close

這個方法是關閉用戶端所開啟的通訊端。與內容管理員搭配使用時，不需要使用它。

close()

create_queue

在指定的帳號下建立新的佇列。

如果已有同名的佇列存在，作業就會失敗。傳回要與新建立佇列互動的用戶端。

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

參數

name: str

必要

要建立的佇列名稱。

metadata: Dict[str, str]

必要

具有name_value組的聽寫，與佇列產生關聯做為中繼資料。範例： {'Category'： 'test'}

timeout: int

timeout 參數以秒為單位。

傳回

新建立之佇列的 QueueClient。

傳回類型

QueueClient

範例

在服務中建立佇列。


   queue_service.create_queue("myqueue1")

delete_queue

刪除指定的佇列及其包含的任何訊息。

成功刪除佇列時，它會立即標示為要刪除，而且用戶端無法再存取。稍後記憶體回收時，將會從佇列服務中移除此佇列。

請注意，刪除佇列可能需要至少 40 秒才能完成。如果在刪除佇列時嘗試對佇列執行作業， <xref:azure.storage.queue.HttpResponseError> 將會擲回。

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

參數

queue: str 或 QueueProperties

必要

要刪除的佇列。這可以是佇列的名稱或 QueueProperties 的實例。

timeout: int

timeout 參數以秒為單位。

傳回類型

None

範例

刪除服務中的佇列。


   queue_service.delete_queue("myqueue1")

from_connection_string

從連接字串建立 QueueServiceClient。

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

參數

conn_str: str

必要

Azure 儲存體帳戶連接字串。

credential

預設值: None

要用來驗證的認證。如果帳戶 URL 已經有 SAS 權杖，或連接字串已經有共用存取金鑰值，則這是選擇性的。此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。此處提供的認證優先于連接字串中的認證。如果使用 AzureNamedKeyCredential 的實例，「name」應該是儲存體帳戶名稱，而「key」應該是儲存體帳戶金鑰。

audience: str

傳回

佇列服務用戶端。

傳回類型

QueueClient

範例

使用連接字串建立 QueueServiceClient。


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

get_queue_client

取得用戶端以與指定的佇列互動。

佇列不需要已經存在。

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

參數

queue: str 或 QueueProperties

必要

佇列。這可以是佇列的名稱或 QueueProperties 的實例。

傳回

QueueClient 物件。

傳回類型

QueueClient

範例

取得佇列用戶端。


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

get_service_properties

取得儲存體帳戶佇列服務的屬性，包括 Azure 儲存體分析。

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

參數

timeout: int

timeout 參數以秒為單位。

傳回

物件，包含佇列服務屬性，例如分析記錄、小時/分鐘計量、cors 規則等。

傳回類型

Dict[str, Any]

範例

取得佇列服務屬性。


   properties = queue_service.get_service_properties()

get_service_stats

擷取與佇列服務的複寫相關的統計資料。

只有在儲存體帳戶啟用讀取權限異地備援複寫時，才能使用。

有了地理備援複寫，Azure 儲存體會以持久的方式在兩個位置維護您的資料。在這兩個位置中，Azure 儲存體會持續維護狀況良好的多個資料複本。您讀取、建立、更新或刪除資料的位置是「主要」儲存體帳戶的位置。主要位置存在於您透過 Azure 管理 Azure 傳統入口網站建立帳戶時所選擇的區域，例如美國中北部。資料複寫的目標位置是「次要」位置。次要位置是根據主要的位置自動判斷而來，它是與主要位置位於相同地區的第二個資料中心。當儲存體帳戶啟用「讀取權限的地理備援複寫」時，可從次要位置使用唯讀權限。

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

參數

timeout: int

timeout 參數以秒為單位。

傳回

佇列服務統計資料。

傳回類型

Dict[str, Any]

list_queues

傳回產生器，以列出指定帳戶下的佇列。

產生器會延遲遵循服務傳回的接續權杖，並在傳回所有佇列時停止。

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

參數

name_starts_with: str

必要

篩選結果，只傳回名稱開頭為指定前置詞的佇列。

include_metadata: bool

必要

指定在回應中傳回佇列中繼資料。

results_per_page: int

每個 API 呼叫要擷取的佇列名稱數目上限。如果要求未指定伺服器，最多會傳回 5,000 個專案。

timeout: int

以秒為單位設定作業的伺服器端逾時。如需詳細資訊，請參閱 https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations 。用戶端上不會追蹤或驗證此值。若要設定用戶端網路逾時，請參閱這裡。此函式可能會對服務進行多個呼叫，在此情況下，指定的逾時值會套用至每個個別呼叫。

傳回

QueueProperties 的可反覆運算 (自動分頁) 。

傳回類型

ItemPaged[QueueProperties]

範例

列出服務中的佇列。


   # 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

設定儲存體帳戶佇列服務的屬性，包括 Azure 儲存體分析。

如果專案 (例如，analytics_logging) 保留為 None，則會保留該服務上的現有設定。

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

參數

analytics_logging: QueueAnalyticsLogging

必要

將 Azure Analytics 記錄設定分組。

hour_metrics: Metrics

必要

小時計量設定會針對佇列每小時匯總，提供依 API 分組的要求統計資料摘要。

minute_metrics: Metrics

必要

分鐘計量設定會針對佇列的每個分鐘提供要求統計資料。

cors: Optional[List[CorsRule]]

必要

您可以在清單中包含最多五個 CorsRule 元素。如果指定了空白清單，則會刪除所有 CORS 規則，且服務會停用 CORS。

timeout: int

timeout 參數以秒為單位。

範例

設定佇列服務屬性。


   # 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)

屬性

api_version

用於要求的儲存體 API 版本。

傳回類型

str

location_mode

用戶端目前使用的位置模式。

根據預設，這會是「主要」。選項包括「主要」和「次要」。

傳回類型

str

primary_endpoint

完整的主要端點 URL。

傳回類型

str

primary_hostname

主要端點的主機名稱。

傳回類型

str

secondary_endpoint

如果已設定，則為完整的次要端點 URL。

如果無法使用，將會引發 ValueError。若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

傳回類型

str

例外狀況

ValueError

secondary_hostname

次要端點的主機名稱。

如果無法使用，則為 None。若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

傳回類型

Optional[str]

url

此實體的完整端點 URL，包括如果使用的 SAS 權杖。

這可能是主要端點或次要端點，視目前的 location_mode 而定。：returns：此實體的完整端點 URL，包括如果使用的 SAS 權杖。：rtype： str

共用方式為

QueueServiceClient 類別

建構函式

參數

範例

方法

close

create_queue

參數

傳回

傳回類型

範例

delete_queue

參數

傳回類型

範例

from_connection_string

參數

傳回

傳回類型

範例

get_queue_client

參數

傳回

傳回類型

範例

get_service_properties

參數

傳回

傳回類型

範例

get_service_stats

參數

傳回

傳回類型

list_queues

參數

傳回

傳回類型

範例

set_service_properties

參數

範例

屬性

api_version

傳回類型

location_mode

傳回類型

primary_endpoint

傳回類型

primary_hostname

傳回類型

secondary_endpoint

傳回類型

例外狀況

secondary_hostname

傳回類型

url

其他資源