Python 用 Azure Purview 共有クライアントライブラリ

[アーティクル]
07/20/2023

Microsoft Purview Share はフルマネージドクラウドサービスです。

このライブラリを使用するには、サービスのドキュメントとプロトコルクライアントドキュメントに大きく依存してください

作業の開始

パッケージをインストールする

pip を使用して Python 用の Azure Purview 共有クライアントライブラリをインストールします。

pip install azure-purview-sharing

前提条件

このパッケージを使用するには、 Azure サブスクリプションと Purview リソースが必要です。
このパッケージを使用するには、Python 3.6 以降が必要です。

クライアントを認証する

Azure Active Directory の使用

このドキュメントでは、 DefaultAzureCredential を使用して Azure Active Directory 経由で認証する方法について説明します。ただし、 azure-identity パッケージによって提供される資格情報はすべて受け入れられます。その他の資格情報の詳細については、 azure-identity のドキュメントを参照してください。

資格情報を選択して構成したら、のインスタンスを PurviewSharingClient作成できます。

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = PurviewSharingClient(endpoint="https://<my-account-name>.purview.azure.com", credential=credential)

主要な概念

データプロバイダー: データプロバイダーとは、データソースを選択して共有を作成し、共有するファイルとフォルダー、および共有するユーザーを選択する個人です。その後、Microsoft Purview から各データコンシューマーに招待が送信されます。

データコンシューマー: データコンシューマーは、共有データへのアクセスに使用する独自の Azure サブスクリプションでターゲットストレージアカウントを指定して、招待を受け入れる個人です。

データプロバイダーの例

次のコード例は、データプロバイダーが Microsoft Azure Python SDK for Purview Sharing を使用して共有アクティビティを管理する方法を示しています。

import os, uuid, json

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint, credential=credential)

データの共有を開始するには、データプロバイダーが最初に、共有するデータを識別する送信済み共有を作成する必要があります。

import os, uuid, json

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint, credential=credential)

sent_share_id = uuid.uuid4()

artifact = {
    "properties": {
        "paths": [
            {
                "containerName": "container-name",
                "receiverPath": "shared-file-name.txt",
                "senderPath": "original/file-name.txt"
            }
        ]
    },
    "storeKind": "AdlsGen2Account",
    "storeReference": {
        "referenceName": "/subscriptions/{subscription-id}/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage",
        "type": "ArmResourceReference"
    }
}

sent_share = {
    "properties": {
        "artifact": artifact,
        "displayName": "sampleShare",
        "description": "A sample share"
    },
    "shareKind": "InPlace"
}

request = client.sent_shares.begin_create_or_replace(
    str(sent_share_id),
    sent_share=sent_share)

response = request.result()
print(response)

送信された共有を作成した後、データプロバイダーは、共有データを表示できるコンシューマーに招待を拡張できます。この例では、電子メールアドレスを指定することで、招待状を個人に拡張します。

import os, uuid

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential
from datetime import date

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint, credential=credential)

sent_share_id = uuid.uuid4()
sent_share_invitation_id = uuid.uuid4()

consumerEmail = "consumer@contoso.com"
today = date.today()
invitation = {
    "invitationKind": "User",
    "properties": {
        "targetEmail": consumerEmail,
        "notify": "true",
        "expirationDate": date(today.year+1,today.month,today.day).strftime("%Y-%m-%d") + " 00:00:00"
    }
}

invitation_request = client.sent_shares.create_invitation(
    sent_share_id=str(sent_share_id),
    sent_share_invitation_id=str(sent_share_invitation_id),
    sent_share_invitation=invitation)

invitation_response = invitation_request.result()
created_invitation = json.loads(invitation_response)
print(created_invitation)

データプロバイダーは、サービスのテナント ID とオブジェクト ID を指定することで、サービスまたはアプリケーションへの招待を拡張することもできます。サービスへの招待の送信に使用されるオブジェクト ID は、(アプリケーション登録ではなく) エンタープライズアプリケーションに関連付けられているオブジェクト ID である必要があります。

import os, uuid

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint, credential=credential)

targetActiveDirectoryId = uuid.uuid4()
targetObjectId = uuid.uuid4()

sent_share_invitation = {
    "invitationKind": "Service",
    "properties": {
        "targetActiveDirectoryId": str(targetActiveDirectoryId),
        "targetObjectId": str(targetObjectId)
    }
}

invitation_response = client.sent_shares.create_invitation(
    sent_share_id=str(sent_share_id),
    sent_share_invitation_id=str(sent_share_invitation_id),
    sent_share_invitation=sent_share_invitation)

print(invitation_response)

送信された共有を作成した後、データプロバイダーはそれを取得できます。

import os, uuid

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()
sent_share_id = uuid.uuid4()

client = PurviewSharingClient(endpoint=endpoint, credential=credential)

retrieved_sent_share = client.sent_shares.get(sent_share_id=str(sent_share_id))
print(retrieved_sent_share)

送信済み共有を一覧表示する

データプロバイダーは、作成した送信済み共有の一覧を取得することもできます。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint, credential=credential)

provider_storage_account_resource_id = "/subscriptions/{subscription-id}/resourceGroups/provider-storage-rg/providers/Microsoft.Storage/storageAccounts/providerstorage"

list_request = client.sent_shares.list(
    reference_name=provider_storage_account_resource_id,
    orderby="properties/createdAt desc")

for list_response in list_request:
    print(list_response)

送信された共有は、データプロバイダーによって削除され、すべてのデータコンシューマーとのデータの共有を停止できます。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

sent_share_id = uuid.uuid4()

delete_request = client.sent_shares.begin_delete(sent_share_id=str(sent_share_id))
delete_response = delete_request.result()
print(delete_response)

送信された共有の招待を作成した後、データプロバイダーはそれを取得できます。

import os, uuid, json

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

sent_share_id = uuid.uuid4()
sent_share_invitation_id = uuid.uuid4()

get_invitation_response = client.sent_shares.get_invitation(
    sent_share_id=str(sent_share_id), 
    sent_share_invitation_id=str(sent_share_invitation_id))

retrieved_share_invitation = json.loads(get_invitation_response)
print(retrieved_share_invitation)

データプロバイダーは、作成した送信済みの共有の招待の一覧を取得することもできます。

import os, uuid, json

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint, credential=credential)

sent_share_id = uuid.uuid4()

list_request = client.sent_shares.list_invitations(sent_share_id=str(sent_share_id))

for list_response in list_request:
    print(list_response)

個々の送信された共有の招待をデータプロバイダーが削除して、招待がアドレス指定された特定のデータコンシューマーとのデータの共有を停止できます。

import os, uuid, json

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

sent_share_id = uuid.uuid4()
sent_share_invitation_id = uuid.uuid4()

delete_invitation_request = client.sent_shares.begin_delete_invitation(
    sent_share_id=str(sent_share_id),
    sent_share_invitation_id=str(sent_share_invitation_id))
delete_invitation_response = delete_invitation_request.result()
print(delete_invitation_response)

データコンシューマーの例

次のコード例は、データコンシューマーが Microsoft Azure Python SDK for Purview Sharing を使用して共有アクティビティを管理する方法を示しています。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

デタッチされた受信共有を一覧表示する

共有されているデータの表示を開始するには、データコンシューマーが最初に、デタッチされた受信共有の一覧を取得する必要があります。このリスト内で、アタッチするデタッチされた受信共有を識別できます。 "デタッチされた" 受信共有とは、受信した共有を指します。この共有は、アタッチされていないか、デタッチされています。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

list_detached_response = client.received_shares.list_detached(orderby="properties/createdAt desc")
print(list_detached_response)

データコンシューマーは、受信した共有を特定したら、受信した共有を共有データにアクセスできる場所にアタッチできます。受信した共有が既にアタッチされている場合は、指定された新しい場所で共有データにアクセスできるようになります。

import os, json

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

consumer_storage_account_resource_id = "/subscriptions/{subscription-id}/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage"

list_detached_response = client.received_shares.list_detached(orderby="properties/createdAt desc")
received_share = next(x for x in list_detached_response)

store_reference = {
    "referenceName": consumer_storage_account_resource_id,
    "type": "ArmResourceReference"
}

sink = {
    "properties": {
        "containerName": "container-test",
        "folder": "folder-test",
        "mountPath": "mountPath-test",
    },
    "storeKind": "AdlsGen2Account",
    "storeReference": store_reference
}

received_share['properties']['sink'] = sink

update_request = client.received_shares.begin_create_or_replace(
    received_share['id'],
    content_type="application/json",
    content=json.dumps(received_share))

update_response = update_request.result()
print(update_response)

データコンシューマーは、受信した個々の共有を取得できます。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

list_detached_response = client.received_shares.list_detached(orderby="properties/createdAt desc")
list_detached = json.loads(list_detached_response)
received_share = list_detached[0]

get_share_response = client.received_shares.get(received_share_id=received_share['id'])
retrieved_share = json.loads(get_share_response)
print(retrieved_share)

添付された受信した共有を一覧表示する

データコンシューマーは、添付された受信共有の一覧を取得することもできます。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

consumer_storage_account_resource_id = "/subscriptions/{subscription-id}/resourceGroups/consumer-storage-rg/providers/Microsoft.Storage/storageAccounts/consumerstorage"

list_attached_response = client.received_shares.list_attached(
    reference_name=consumer_storage_account_resource_id,
    orderby="properties/createdAt desc")
print(list_attached_response)

受信した共有をデータコンシューマーが削除して、共有データへのアクセスを終了できます。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

delete_received_share_request = client.received_shares.begin_delete(received_share_id=received_share['id'])
delete_received_share_response = delete_received_share_request.result()
print(delete_received_share_response)

次のコード例は、Microsoft Azure Python SDK for Purview Sharing を使用して共有リソースを表示する方法を示しています。共有リソースは、プロバイダーがデータを共有する基になるリソース、またはコンシューマーが共有するデータをアタッチする宛先です。

共有リソースの一覧を取得して、共有アクティビティが行われたアカウント内のすべてのリソースを表示できます。

import os

from azure.purview.sharing import PurviewSharingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["ENDPOINT"]
credential = DefaultAzureCredential()

client = PurviewSharingClient(endpoint=endpoint,credential=credential)

list_request = client.share_resources.list(
    filter="properties/storeKind eq 'AdlsGen2Account'",
    orderby="properties/createdAt desc")

for list_response in list_request:
    print(list_response)

トラブルシューティング

全般

応答でを呼び出.raise_for_status()すと、Purview Catalog クライアントによって、Azure Core で定義されている例外が発生します。

ログの記録

このライブラリでは、標準のログ記録ライブラリを使用してログを記録します。 HTTP セッション (URL、ヘッダーなど) に関する基本情報は INFO レベルでログに記録されます。

要求/応答本文と編集されていないヘッダーを含む詳細なデバッグレベルのログ記録は、次のように logging_enable キーワード引数を使用してクライアントで有効にすることができます。

import sys
import logging
from azure.identity import DefaultAzureCredential
from azure.purview.sharing import PurviewSharingClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "https://<my-account-name>.share.purview.azure.com"
credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = PurviewSharingClient(endpoint=endpoint, credential=credential, logging_enable=True)

同様に、 logging_enable クライアントで有効になっていない場合でも、1 回 send_request の呼び出しに対して詳細なログ記録を有効にすることができます。

result = client.types.get_all_type_definitions(logging_enable=True)

次のステップ

より一般的なサンプルについては、サンプルを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、「 cla.microsoft.com」を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

次の方法で共有

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

Azure Active Directory の使用

主要な概念

例

データプロバイダーの例

送信済み共有を一覧表示する

データコンシューマーの例

デタッチされた受信共有を一覧表示する

添付された受信した共有を一覧表示する

トラブルシューティング

全般

ログの記録

次のステップ

共同作成

その他のリソース

次の方法で共有

Python 用 Azure Purview 共有クライアント ライブラリ - バージョン 1.0.0b3

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

Azure Active Directory の使用

主要な概念

例

データ プロバイダーの例

送信済み共有クライアントを作成する

共有を作成する

共有の招待をユーザーに送信する

共有の招待をサービスに送信する

送信済み共有の取得

送信済み共有を一覧表示する

送信済み共有の削除

送信済み共有の招待を取得する

送信済み共有の招待を一覧表示する

送信済み共有の招待を削除する

データ コンシューマーの例

受信した共有クライアントを作成する

デタッチされた受信共有を一覧表示する

受信した共有をアタッチする

Get Received Share

添付された受信した共有を一覧表示する

受信した共有の削除

リソースの共有の例

共有リソースの一覧表示

トラブルシューティング

全般

ログの記録

次のステップ

共同作成

その他のリソース

Python 用 Azure Purview 共有クライアントライブラリ - バージョン 1.0.0b3

データプロバイダーの例

データコンシューマーの例