Share via

ShareServiceClient 類別

  • 參考

在帳戶層級與檔案共用服務互動的用戶端。

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

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

繼承
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
ShareServiceClient

建構函式

ShareServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, *, token_intent: Literal['backup'] | 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」 應該是儲存體帳戶金鑰。
token_intent
Literal['backup']

使用 TokenCredential 進行驗證時需要，並忽略其他類型的驗證。 指定使用 TokenCredential 驗證時所有要求的意圖。 可能的值包括：

backup - 指定要求適用于備份/系統管理員類型作業，這表示會略過所有檔案/目錄 ACL，並授與完整許可權。 使用者也必須具有必要的 RBAC 許可權。

allow_trailing_dot
bool

如果為 true，則不會從目標 URI 修剪尾端點。

allow_source_trailing_dot
bool

如果為 true，則不會從來源 URI 修剪尾端點。

api_version
str

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

12.1.0 版的新功能。

secondary_hostname
str

次要端點的主機名稱。

max_range_size
int

用於檔案上傳的最大範圍大小。 預設值為 4*1024*1024。

範例

使用 URL 和認證建立共用服務用戶端。


   from azure.storage.fileshare import ShareServiceClient
   share_service_client = ShareServiceClient(
       account_url=self.account_url,
       credential=self.access_key
   )

方法

close

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

在指定的帳號下建立新的共用。 如果相同名稱的共用已經存在，作業會失敗。 傳回要與新建立共用互動的用戶端。
delete_share

標記要刪除的指定共用。 共用稍後會在垃圾收集期間刪除。
from_connection_string

從連接字串建立 ShareServiceClient。
get_service_properties

取得儲存體帳戶檔案共用服務的屬性，包括 Azure 儲存體分析。
get_share_client

取得用戶端以與指定的共用互動。 共用不需要已經存在。
list_shares

傳回可逐一逐一檢視指定帳戶下類似 Dict 的 ShareProperties 自動分頁。 產生器會延遲遵循服務傳回的接續權杖，並在傳回所有共用時停止。
set_service_properties

設定儲存體帳戶檔案共用服務的屬性，包括 Azure 儲存體分析。 如果專案 (例如，hour_metrics) 保留為 None，則會保留該服務上的現有設定。
undelete_share

還原虛刪除的共用。

只有在刪除保留原則中指定的天數內使用時，作業才會成功。

12.2.0 版的新功能：此作業是在 API 版本 '2019-12-12' 中引進。

close

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

close()

create_share

在指定的帳號下建立新的共用。 如果相同名稱的共用已經存在，作業會失敗。 傳回要與新建立共用互動的用戶端。

create_share(share_name: str, **kwargs) -> ShareClient

參數

share_name
str
必要

要建立的共用名稱稱。

metadata
dict(str,str)

具有name_value組的聽寫，與共享建立關聯為中繼資料。 範例：{'Category'：'test'}

quota
int

以位元組為單位的配額。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

新建立共用的 ShareClient。

傳回類型

ShareClient

範例

在檔案共用服務中建立共用。


   file_service.create_share(share_name="fileshare1")

delete_share

標記要刪除的指定共用。 共用稍後會在垃圾收集期間刪除。

delete_share(share_name: ShareProperties | str, delete_snapshots: bool | None = False, **kwargs) -> None

參數

share_name
str 或 ShareProperties
必要

要刪除的共用。 這可以是共用的名稱或 ShareProperties 的實例。

delete_snapshots
bool
必要

指出是否要刪除快照集。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回類型

None

範例

刪除檔案共用服務中的共用。


   file_service.delete_share(share_name="fileshare1")

from_connection_string

從連接字串建立 ShareServiceClient。

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 類別實例。 如果資源 URI 已經包含 SAS 權杖，則會忽略此權杖，以取得明確的認證

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

傳回

檔案共用服務用戶端。

傳回類型

ShareServiceClient

範例

使用連接字串建立共用服務用戶端。


   from azure.storage.fileshare import ShareServiceClient
   share_service_client = ShareServiceClient.from_connection_string(self.connection_string)

get_service_properties

取得儲存體帳戶檔案共用服務的屬性，包括 Azure 儲存體分析。

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

參數

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

包含檔案服務屬性的字典，例如分析記錄、小時/分鐘計量、cors 規則等等。

傳回類型

Dict[str, Any]

範例

取得檔案共用服務屬性。


   properties = file_service.get_service_properties()

get_share_client

取得用戶端以與指定的共用互動。 共用不需要已經存在。

get_share_client(share: ShareProperties | str, snapshot: Dict[str, Any] | str | None = None) -> ShareClient

參數

share
str 或 ShareProperties
必要

共用。 這可以是共用的名稱或 ShareProperties 的實例。

snapshot
str
預設值: None

要在其中運作的選擇性共用快照集。 這可以是快照集識別碼字串或從 <xref:azure.storage.fileshare.create_snapshot> 傳回的回應。

傳回

ShareClient。

傳回類型

ShareClient

範例

取得共用用戶端。


   from azure.storage.fileshare import ShareServiceClient
   file_service = ShareServiceClient.from_connection_string(self.connection_string)

   # Get a share client to interact with a specific share
   share = file_service.get_share_client("fileshare2")

list_shares

傳回可逐一逐一檢視指定帳戶下類似 Dict 的 ShareProperties 自動分頁。 產生器會延遲遵循服務傳回的接續權杖，並在傳回所有共用時停止。

list_shares(name_starts_with: str | None = None, include_metadata: bool | None = False, include_snapshots: bool | None = False, **kwargs) -> ItemPaged[ShareProperties]

參數

name_starts_with
str
必要

篩選結果，只傳回名稱開頭為指定name_starts_with的共用。

include_metadata
bool
必要

指定在回應中傳回共用中繼資料。

include_snapshots
bool
必要

指定在回應中傳回共用快照集。

include_deleted
bool

指定在回應中傳回已刪除的共用。 這僅適用于已啟用共用虛刪除的帳戶。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

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

傳回類型

ItemPaged[ShareProperties]

範例

列出檔案共用服務中的共用。


   # List the shares in the file service
   my_shares = list(file_service.list_shares())

   # Print the shares
   for share in my_shares:
       print(share)

set_service_properties

設定儲存體帳戶檔案共用服務的屬性，包括 Azure 儲存體分析。 如果專案 (例如，hour_metrics) 保留為 None，則會保留該服務上的現有設定。

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

參數

hour_metrics
Metrics
必要

小時計量設定會提供依 API 分組的要求統計資料摘要，以每小時匯總檔案。

minute_metrics
Metrics
必要

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

cors
list(CorsRule)
必要

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

protocol
ShareProtocolSettings
必要

設定通訊協定設定

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回類型

None

範例

設定檔案共用服務屬性。


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

   # 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
   file_service.set_service_properties(hour_metrics, minute_metrics, cors)

undelete_share

還原虛刪除的共用。

只有在刪除保留原則中指定的天數內使用時，作業才會成功。

12.2.0 版的新功能：此作業是在 API 版本 '2019-12-12' 中引進。

undelete_share(deleted_share_name: str, deleted_share_version: str, **kwargs: Any) -> ShareClient

參數

deleted_share_name
str
必要

指定要還原的已刪除共用名稱稱。

deleted_share_version
str
必要

指定要還原的已刪除共用版本。

timeout
int

以秒為單位設定作業的伺服器端逾時。 如需詳細資訊，請參閱 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

未刪除共用的 ShareClient。

傳回類型

ShareClient

屬性

api_version

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

location_mode

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

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

primary_endpoint

完整的主要端點 URL。

primary_hostname

主要端點的主機名稱。

secondary_endpoint

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

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

例外狀況

ValueError

secondary_hostname

次要端點的主機名稱。

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

url

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

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