Share via

Biblioteca de cliente de Partilha do Azure Purview para Python – versão 1.0.0b3

  • Artigo

O Microsoft Purview Share é um serviço cloud totalmente gerido.

Confie fortemente na documentação do serviço e nos nossos documentos de cliente de protocolo para utilizar esta biblioteca

Código fonte | Pacote (PyPI) | Documentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de cliente de Partilha do Azure Purview para Python com pip:

pip install azure-purview-sharing

Pré-requisitos

Autenticar o cliente

Utilizar o Azure Active Directory

Este documento demonstra a utilização de DefaultAzureCredential para autenticar através do Azure Active Directory. No entanto, qualquer uma das credenciais oferecidas pelo pacote azure-identity será aceite. Veja a documentação do azure-identity para obter mais informações sobre outras credenciais.

Assim que tiver escolhido e configurado a sua credencial, pode criar instâncias do 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)

Conceitos-chave

Fornecedor de Dados: Um fornecedor de dados é o indivíduo que cria uma partilha ao selecionar uma origem de dados, escolher os ficheiros e pastas a partilhar e com quem partilhá-los. Em seguida, o Microsoft Purview envia um convite a cada consumidor de dados.

Consumidor de Dados: Um consumidor de dados é o indivíduo que aceita o convite ao especificar uma conta de armazenamento de destino na sua própria subscrição do Azure que irá utilizar para aceder aos dados partilhados.

Exemplos

Índice:

Exemplos do Fornecedor de Dados

Os exemplos de código seguintes demonstram como os fornecedores de dados podem utilizar o SDK Python do Microsoft Azure para a Partilha do Purview para gerir a respetiva atividade de partilha.

Criar um Cliente de Partilha Enviada

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)

Criar Partilha

Para começar a partilhar dados, o fornecedor de dados tem primeiro de criar uma partilha enviada que identifique os dados que pretende partilhar.

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)

Enviar Convite de Partilha a um Utilizador

Depois de criar uma partilha enviada, o fornecedor de dados pode alargar os convites aos consumidores que possam ver os dados partilhados. Neste exemplo, um convite é alargado a um indivíduo ao especificar o respetivo endereço de e-mail.

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)

Enviar Convite de Partilha para um Serviço

Os fornecedores de dados também podem expandir convites para serviços ou aplicações ao especificar o ID do inquilino e o ID do objeto do serviço. O ID de objeto utilizado para enviar um convite para um serviço tem de ser o ID do objeto associado à Aplicação Enterprise (não o registo da aplicação).

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)

Obter Partilha Enviada

Depois de criar uma partilha enviada, os fornecedores de dados podem recuperá-la.

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)

Listar Partilhas Enviadas

Os fornecedores de dados também podem obter uma lista das partilhas enviadas que criaram.

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)

Eliminar Partilha Enviada

Uma partilha enviada pode ser eliminada pelo fornecedor de dados para parar de partilhar os dados com todos os consumidores de dados.

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)

Receber Convite de Partilha Enviado

Depois de criar um convite de partilha enviado, os fornecedores de dados podem recuperá-lo.

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)

Listar Convites de Partilha Enviados

Os fornecedores de dados também podem obter uma lista dos convites de partilha enviados que criaram.

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)

Eliminar Convite de Partilha Enviada

Um convite de partilha enviado individualmente pode ser eliminado pelo fornecedor de dados para parar de partilhar os seus dados com o consumidor de dados específico a quem o convite foi abordado.

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)

Exemplos de Consumidor de Dados

Os exemplos de código seguintes demonstram como os consumidores de dados podem utilizar o SDK Python do Microsoft Azure para a Partilha do Purview para gerir a respetiva atividade de partilha.

Criar um Cliente de Partilha Recebida

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)

Lista de Partilhas Recebidas Desanexadas

Para começar a ver os dados partilhados com os mesmos, um consumidor de dados tem primeiro de obter uma lista de partilhas recebidas desanexadas. Nesta lista, podem identificar uma partilha recebida desanexada para anexar. Uma partilha recebida "desanexada" refere-se a uma partilha recebida que nunca foi anexada ou foi desanexada.

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)

Anexar uma Partilha Recebida

Depois de o consumidor de dados identificar uma partilha recebida, pode anexar a partilha recebida a uma localização onde possa aceder aos dados partilhados. Se a partilha recebida já estiver anexada, os dados partilhados serão tornados acessíveis na nova localização especificada.

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)

Obter Partilha Recebida

Um consumidor de dados pode obter uma partilha recebida individualmente.

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)

Listar Partilhas Recebidas Anexadas

Os consumidores de dados também podem obter uma lista das respetivas partilhas recebidas anexadas.

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)

Eliminar Partilha Recebida

Uma partilha recebida pode ser eliminada pelo consumidor de dados para terminar o acesso aos dados partilhados.

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)

Partilhar Exemplos de Recursos

Os exemplos de código seguintes demonstram como utilizar o SDK Python do Microsoft Azure para Partilha do Purview para ver recursos de partilha. Um recurso de partilha é o recurso subjacente a partir do qual um fornecedor partilha dados ou o destino em que um consumidor anexa dados partilhados com os mesmos.

Listar Recursos de Partilha

Pode obter uma lista de recursos de partilha para ver todos os recursos numa conta onde tenham ocorrido atividades de partilha.

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)

Resolução de problemas

Geral

O cliente do Catálogo purview irá gerar exceções definidas no Azure Core se chamar .raise_for_status() as suas respostas.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registos. As informações básicas sobre as sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo ao nível de DEBUG detalhado, incluindo corpos de pedido/resposta e cabeçalhos não retotados, pode ser ativado num cliente com o logging_enable argumento palavra-chave:

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)

Da mesma forma, logging_enable pode ativar o registo detalhado de uma única send_request chamada, mesmo quando não está ativada para o cliente:

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

Passos seguintes

Para obter exemplos mais genéricos, veja os nossos exemplos.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.