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 トークンが既に含まれている場合、明示的な資格情報を優先して無視されます

  • ただし、競合する SAS トークンによって ValueError が発生する AzureSasCredential の場合を除きます。 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

要求に使用する Storage 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 Storage Analyticsを含むストレージ アカウントのファイル共有サービスのプロパティを取得します。
get_share_client

指定した共有と対話するクライアントを取得します。 共有がまだ存在している必要はありません。
list_shares

指定したアカウントの dict に似た ShareProperties の自動ページング iterable を返します。 ジェネレーターは、サービスによって返された継続トークンに遅れて従い、すべての共有が返されたときに停止します。
set_service_properties

Azure Storage Analyticsを含むストレージ アカウントのファイル共有サービスのプロパティを設定します。 要素 (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 Storage アカウントへの接続文字列。

credential
既定値: None

認証に使用する資格情報。 アカウント URL に SAS トークンが既に含まれている場合、これは省略可能です。 値には、SAS トークン文字列、azure.core.credentials の AzureSasCredential または AzureNamedKeyCredential のインスタンス、アカウント共有アクセス キー、または azure.identity からの TokenCredentials クラスのインスタンスを指定できます。 リソース URI に SAS トークンが既に含まれている場合、明示的な資格情報を優先して無視されます

  • ただし、競合する SAS トークンによって ValueError が発生する AzureSasCredential の場合を除きます。 AzureNamedKeyCredential のインスタンスを使用する場合は、"name" をストレージ アカウント名に、"key" をストレージ アカウント キーにする必要があります。

戻り値

ファイル共有サービス クライアント。

の戻り値の型 :

ShareServiceClient

例

接続文字列を使用して共有サービス クライアントを作成します。


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

get_service_properties

Azure Storage Analyticsを含むストレージ アカウントのファイル共有サービスのプロパティを取得します。

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

操作するオプションの共有スナップショット。 これは、スナップショット ID 文字列、または から<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 の自動ページング iterable を返します。 ジェネレーターは、サービスによって返された継続トークンに遅れて従い、すべての共有が返されたときに停止します。

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 の iterable (自動ページング) です。

の戻り値の型 :

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 Storage Analyticsを含むストレージ アカウントのファイル共有サービスのプロパティを設定します。 要素 (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
必須

分単位のメトリック設定では、ファイルの 1 分ごとの要求統計が提供されます。

cors
list(CorsRule)
必須

リストには、最大 5 つの 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

要求に使用される Storage API のバージョン。

location_mode

クライアントが現在使用している場所モード。

既定では、これは "プライマリ" になります。 オプションには、"primary" と "secondary" が含まれます。

primary_endpoint

完全なプライマリ エンドポイント URL。

primary_hostname

プライマリ エンドポイントのホスト名。

secondary_endpoint

完全なセカンダリ エンドポイント URL (構成されている場合)。

使用できない場合は、ValueError が発生します。 セカンダリ ホスト名を明示的に指定するには、インスタンス化時に省略可能な secondary_hostname キーワード (keyword) 引数を使用します。

例外

ValueError

secondary_hostname

セカンダリ エンドポイントのホスト名。

使用できない場合、これは None になります。 セカンダリ ホスト名を明示的に指定するには、インスタンス化時に省略可能な secondary_hostname キーワード (keyword) 引数を使用します。

url

SAS トークン (使用されている場合) を含む、このエンティティへの完全なエンドポイント URL。

これは、現在 location_modeの に応じて、プライマリ エンドポイントまたはセカンダリ エンドポイントのいずれかになります。 :returns: SAS トークン (使用されている場合) を含む、このエンティティへの完全なエンドポイント URL。 :rtype: str