مشاركة عبر

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 المميز أو مثيل AzureSasCredential أو AzureNamedKeyCredential من azure.core.credentials أو مفتاح وصول مشترك للحساب أو مثيل فئة TokenCredentials من azure.identity. إذا كان عنوان URI للمورد يحتوي بالفعل على رمز SAS المميز، فسيتم تجاهل هذا لصالح بيانات اعتماد صريحة

  • باستثناء حالة AzureSasCredential، حيث سترفع رموز SAS المميزة المتعارضة ValueError. إذا كنت تستخدم مثيل AzureNamedKeyCredential، يجب أن يكون "الاسم" هو اسم حساب التخزين، ويجب أن يكون "المفتاح" هو مفتاح حساب التخزين.
api_version
str

إصدار Storage API لاستخدامه للطلبات. القيمة الافتراضية هي أحدث إصدار خدمة متوافق مع SDK الحالي. قد يؤدي الإعداد إلى إصدار أقدم إلى تقليل توافق الميزات.

secondary_hostname
str

اسم مضيف نقطة النهاية الثانوية.

audience
str

الجمهور الذي يجب استخدامه عند طلب الرموز المميزة لمصادقة Azure Active Directory. يكون له تأثير فقط عندما تكون بيانات الاعتماد من نوع TokenCredential. قد تكون https://storage.azure.com/ القيمة (افتراضية) أو https://.queue.core.windows.net.

أمثلة

إنشاء QueueServiceClient باستخدام عنوان URL للحساب وبيانات الاعتماد.


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

إنشاء QueueServiceClient باستخدام بيانات اعتماد Azure Identity.


   # 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 Storage Analytics.
get_service_stats

استرداد الإحصائيات المتعلقة بالنسخ المتماثل لخدمة قائمة الانتظار.

يتوفر فقط عند تمكين النسخ المتماثل المتكرر جغرافيا للوصول إلى القراءة لحساب التخزين.

مع النسخ المتماثل الجغرافي المتكرر، يحافظ Azure Storage على بياناتك الدائمة في موقعين. في كلا الموقعين، يحتفظ Azure Storage باستمرار بنسخ متماثلة صحية متعددة من بياناتك. الموقع الذي تقرأ فيه البيانات أو تنشئها أو تحدثها أو تحذفها هو موقع حساب التخزين الأساسي. يوجد الموقع الأساسي في المنطقة التي تختارها في الوقت الذي تنشئ فيه حسابا عبر مدخل Azure Management Azure الكلاسيكي، على سبيل المثال، شمال وسط الولايات المتحدة. الموقع الذي يتم نسخ بياناتك إليه هو الموقع الثانوي. يتم تحديد الموقع الثانوي تلقائيا استنادا إلى موقع الأساسي؛ وهو في مركز بيانات ثان موجود في نفس المنطقة مثل الموقع الأساسي. يتوفر الوصول للقراءة فقط من الموقع الثانوي، إذا تم تمكين النسخ المتماثل المتكرر جغرافيا للوصول للقراءة لحساب التخزين الخاص بك.
list_queues

إرجاع منشئ لسرد قوائم الانتظار ضمن الحساب المحدد.

سيتبع المولد ببطء الرموز المميزة للاستمرار التي تم إرجاعها بواسطة الخدمة ويتوقف عند إرجاع جميع قوائم الانتظار.
set_service_properties

تعيين خصائص خدمة قائمة الانتظار لحساب التخزين، بما في ذلك Azure Storage Analytics.

إذا تم ترك عنصر (على سبيل المثال analytics_logging) ك بلا، يتم الاحتفاظ بالإعدادات الموجودة على الخدمة لتلك الوظيفة.

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

يتم التعبير عن معلمة المهلة بالثوان.

المرتجعات

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

يتم التعبير عن معلمة المهلة بالثوان.

نوع الإرجاع

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 Storage.

credential
القيمة الافتراضية: None

بيانات الاعتماد التي يجب المصادقة بها. هذا اختياري إذا كان عنوان URL للحساب يحتوي بالفعل على رمز SAS مميز، أو كان سلسلة الاتصال يحتوي بالفعل على قيم مفتاح وصول مشتركة. يمكن أن تكون القيمة سلسلة رمز SAS المميز أو مثيل AzureSasCredential أو AzureNamedKeyCredential من azure.core.credentials أو مفتاح وصول مشترك للحساب أو مثيل فئة TokenCredentials من azure.identity. ستكون لبيانات الاعتماد المقدمة هنا الأسبقية على تلك الموجودة في سلسلة الاتصال. إذا كنت تستخدم مثيل AzureNamedKeyCredential، يجب أن يكون "الاسم" هو اسم حساب التخزين، ويجب أن يكون "المفتاح" هو مفتاح حساب التخزين.

audience
str

الجمهور الذي يجب استخدامه عند طلب الرموز المميزة لمصادقة Azure Active Directory. يكون له تأثير فقط عندما تكون بيانات الاعتماد من نوع TokenCredential. قد تكون https://storage.azure.com/ القيمة (افتراضية) أو https://.queue.core.windows.net.

المرتجعات

عميل خدمة قائمة الانتظار.

نوع الإرجاع

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 Storage Analytics.

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

المعلمات

timeout
int

يتم التعبير عن معلمة المهلة بالثوان.

المرتجعات

كائن يحتوي على خصائص خدمة قائمة الانتظار مثل تسجيل التحليلات ومقاييس الساعة/الدقيقة وقواعد cors وما إلى ذلك.

نوع الإرجاع

Dict[str, Any]

أمثلة

الحصول على خصائص خدمة قائمة الانتظار.


   properties = queue_service.get_service_properties()

get_service_stats

استرداد الإحصائيات المتعلقة بالنسخ المتماثل لخدمة قائمة الانتظار.

يتوفر فقط عند تمكين النسخ المتماثل المتكرر جغرافيا للوصول إلى القراءة لحساب التخزين.

مع النسخ المتماثل الجغرافي المتكرر، يحافظ Azure Storage على بياناتك الدائمة في موقعين. في كلا الموقعين، يحتفظ Azure Storage باستمرار بنسخ متماثلة صحية متعددة من بياناتك. الموقع الذي تقرأ فيه البيانات أو تنشئها أو تحدثها أو تحذفها هو موقع حساب التخزين الأساسي. يوجد الموقع الأساسي في المنطقة التي تختارها في الوقت الذي تنشئ فيه حسابا عبر مدخل Azure Management Azure الكلاسيكي، على سبيل المثال، شمال وسط الولايات المتحدة. الموقع الذي يتم نسخ بياناتك إليه هو الموقع الثانوي. يتم تحديد الموقع الثانوي تلقائيا استنادا إلى موقع الأساسي؛ وهو في مركز بيانات ثان موجود في نفس المنطقة مثل الموقع الأساسي. يتوفر الوصول للقراءة فقط من الموقع الثانوي، إذا تم تمكين النسخ المتماثل المتكرر جغرافيا للوصول للقراءة لحساب التخزين الخاص بك.

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

المعلمات

timeout
int

يتم التعبير عن معلمة المهلة بالثوان.

المرتجعات

إحصائيات خدمة قائمة الانتظار.

نوع الإرجاع

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. إذا لم يحدد الطلب، فسيرجع الخادم ما يصل إلى 5000 عنصر.

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 Storage Analytics.

إذا تم ترك عنصر (على سبيل المثال analytics_logging) ك بلا، يتم الاحتفاظ بالإعدادات الموجودة على الخدمة لتلك الوظيفة.

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
مطلوب

توفر إعدادات مقاييس الساعة ملخصا لإحصائيات الطلب المجمعة بواسطة واجهة برمجة التطبيقات في تجميعات بالساعة لقوائم الانتظار.

minute_metrics
Metrics
مطلوب

توفر إعدادات مقاييس الدقيقة إحصائيات الطلب لكل دقيقة لقوائم الانتظار.

cors
Optional[List[CorsRule]]
مطلوب

يمكنك تضمين ما يصل إلى خمسة عناصر CorsRule في القائمة. إذا تم تحديد قائمة فارغة، فسيتم حذف جميع قواعد CORS، وسيتم تعطيل CORS للخدمة.

timeout
int

يتم التعبير عن معلمة المهلة بالثوان.

أمثلة

تعيين خصائص خدمة قائمة الانتظار.


   # 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

إصدار واجهة برمجة تطبيقات التخزين المستخدمة للطلبات.

نوع الإرجاع

str

location_mode

وضع الموقع الذي يستخدمه العميل حاليا.

بشكل افتراضي، سيكون هذا "أساسي". تتضمن الخيارات "الأساسي" و"الثانوي".

نوع الإرجاع

str

primary_endpoint

عنوان URL الكامل لنقطة النهاية الأساسية.

نوع الإرجاع

str

primary_hostname

اسم مضيف نقطة النهاية الأساسية.

نوع الإرجاع

str

secondary_endpoint

عنوان URL لنقطة النهاية الثانوية الكاملة إذا تم تكوينه.

إذا لم يكن متوفرا، فسيتم رفع ValueError. لتحديد اسم مضيف ثانوي بشكل صريح، استخدم وسيطة الكلمة الأساسية secondary_hostname الاختيارية عند إنشاء مثيل.

نوع الإرجاع

str

استثناءات

ValueError

secondary_hostname

اسم مضيف نقطة النهاية الثانوية.

إذا لم يكن متوفرا، فسيكون هذا بلا. لتحديد اسم مضيف ثانوي بشكل صريح، استخدم وسيطة الكلمة الأساسية secondary_hostname الاختيارية عند إنشاء مثيل.

نوع الإرجاع

Optional[str]

url

عنوان URL الكامل لنقطة النهاية لهذا الكيان، بما في ذلك رمز SAS المميز إذا تم استخدامه.

قد تكون هذه إما نقطة النهاية الأساسية، أو نقطة النهاية الثانوية اعتمادا على الحالي location_mode. :returns: عنوان URL الكامل لنقطة النهاية لهذا الكيان، بما في ذلك رمز SAS المميز إذا تم استخدامه. :rtype: str