External Data Shares Provider - Create External Data Share

Serviço:
Core
Versão da API:
v1

Cria um compartilhamento de dados externos para um determinado caminho ou lista de caminhos no item especificado.

Permissions

O chamador deve ter permissões de leitura e recompartilhamento no item.

Escopos delegados necessários

As APIs de item podem ter um destes escopos em seu token:

  • Escopo genérico: Item.ExternalDataShare.All
  • Âmbito específico: itemType. ExternalDataShare.All, por exemplo: Lakehouse.ExternalDataShare.All

Para obter mais informações sobre escopos, consulte o artigo escopos.

Configurações de locatário necessárias

Para usar essa API, habilite a opção Administrador de compartilhamento de dados externo para a entidade de chamada.

Limitations

Máximo de 10 pedidos por minuto.

Tipos de item suportados: Consulte Compartilhamento de dados externos no Microsoft Fabric - Tipos de item suportados.

Identidades suportadas pelo Entra da Microsoft

Esta API suporta as identidades do Microsoft listadas nesta secção.

Identity Support
User Yes
Entidade de serviço e identidades geridas Yes

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/externalDataShares

Parâmetros do URI

Name Em Necessário Tipo Description
itemId
 path True

string (uuid)

O ID do item.
workspaceId
 path True

string (uuid)

O ID do espaço de trabalho.

Corpo do Pedido

Name Necessário Tipo Description
paths True

string[]

O caminho ou lista de caminhos que devem ser compartilhados externamente. Você pode compartilhar até 100 caminhos em cada compartilhamento. Um caminho válido para um compartilhamento de dados externo deve começar com "Arquivos/" ou "Tabelas/". Você não pode compartilhar a pasta raiz em si (Arquivos ou Tabelas).

Por exemplo, estes caminhos são válidos:

  • "Files/MyFolder1"

  • "Tabelas/MySchema"

  • "Tables/MyTable1"
recipient True BaseExternalDataShareRecipient:

O destinatário convidado a aceitar o compartilhamento de dados externos.

Respostas

Name Tipo Description
201 Created

ExternalDataShare

Criado com sucesso.

Cabeçalhos

Location: string
429 Too Many Requests

ErrorResponse

O limite de tarifa de serviço foi ultrapassado. O servidor devolve um Retry-After cabeçalho que indica, em segundos, quanto tempo o cliente deve esperar antes de enviar pedidos adicionais.

Cabeçalhos

Retry-After: integer
Other Status Codes

ErrorResponse

Códigos de erro comuns:

  • UnknownError - Ocorreu um erro.

Exemplos

Create an external data share example
Create an external data share with a specific recipient tenant ID example
Create an external data share with multiple paths example
Create an external data share with recipient object ID example

Create an external data share example

Pedido de amostra

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares

{
  "paths": [
    "Files/Sales/Contoso_Sales_2023"
  ],
  "recipient": {
    "type": "User",
    "userPrincipalName": "lisa@fabrikam.com"
  }
}

Resposta da amostra

Código de estado:
201 
Location: https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares/dccc162f-7a41-4720-83c3-5c7e81187959
{
  "id": "dccc162f-7a41-4720-83c3-5c7e81187959",
  "paths": [
    "Files/Sales/Contoso_Sales_2023"
  ],
  "creatorPrincipal": {
    "id": "f3052d1c-61a9-46fb-8df9-0d78916ae041",
    "type": "User"
  },
  "recipient": {
    "type": "User",
    "userPrincipalName": "lisa@fabrikam.com"
  },
  "status": "Pending",
  "expirationTimeUtc": "2024-12-13T00:00:00.000Z",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "itemId": "5b218778-e7a5-4d73-8187-f10824047715",
  "invitationUrl": "https://app.fabric.microsoft.com/externaldatasharing/accept?providerTenantId=34f92457-fe9d-4c36-92a8-499fdfaf0f8f&shareId=dccc162f-7a41-4720-83c3-5c7e81187959"
}

Create an external data share with a specific recipient tenant ID example

Pedido de amostra

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares

{
  "paths": [
    "Files/Sales/Contoso_Sales_2023"
  ],
  "recipient": {
    "type": "User",
    "userPrincipalName": "lisa@fabrikam.com",
    "tenantId": "c51dc03f-268a-4da0-a879-25f24947ab8b"
  }
}

Resposta da amostra

Código de estado:
201 
Location: https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares/dccc162f-7a41-4720-83c3-5c7e81187959
{
  "id": "dccc162f-7a41-4720-83c3-5c7e81187959",
  "paths": [
    "Files/Sales/Contoso_Sales_2023"
  ],
  "creatorPrincipal": {
    "id": "f3052d1c-61a9-46fb-8df9-0d78916ae041",
    "type": "User"
  },
  "recipient": {
    "type": "User",
    "userPrincipalName": "lisa@fabrikam.com",
    "tenantId": "c51dc03f-268a-4da0-a879-25f24947ab8b"
  },
  "status": "Pending",
  "expirationTimeUtc": "2024-12-13T00:00:00.000Z",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "itemId": "5b218778-e7a5-4d73-8187-f10824047715",
  "invitationUrl": "https://app.fabric.microsoft.com/externaldatasharing/accept?providerTenantId=34f92457-fe9d-4c36-92a8-499fdfaf0f8f&shareId=dccc162f-7a41-4720-83c3-5c7e81187959"
}

Create an external data share with multiple paths example

Pedido de amostra

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares

{
  "paths": [
    "Files/Sales/Contoso_Sales_2023",
    "Files/Sales/Contoso_Sales_2024/SubFolder1",
    "Files/Sales/Contoso_Sales_2024/SubFolder2/SubFolder3"
  ],
  "recipient": {
    "type": "User",
    "userPrincipalName": "lisa@fabrikam.com"
  }
}

Resposta da amostra

Código de estado:
201 
Location: https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares/dccc162f-7a41-4720-83c3-5c7e81187959
{
  "id": "dccc162f-7a41-4720-83c3-5c7e81187959",
  "paths": [
    "Files/Sales/Contoso_Sales_2023",
    "Files/Sales/Contoso_Sales_2024/SubFolder1",
    "Files/Sales/Contoso_Sales_2024/SubFolder2/SubFolder3"
  ],
  "creatorPrincipal": {
    "id": "f3052d1c-61a9-46fb-8df9-0d78916ae041",
    "type": "User"
  },
  "recipient": {
    "type": "User",
    "userPrincipalName": "lisa@fabrikam.com"
  },
  "status": "Pending",
  "expirationTimeUtc": "2024-12-13T00:00:00.000Z",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "itemId": "5b218778-e7a5-4d73-8187-f10824047715",
  "invitationUrl": "https://app.fabric.microsoft.com/externaldatasharing/accept?providerTenantId=34f92457-fe9d-4c36-92a8-499fdfaf0f8f&shareId=dccc162f-7a41-4720-83c3-5c7e81187959"
}

Create an external data share with recipient object ID example

Pedido de amostra

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares

{
  "paths": [
    "Files/Sales/Contoso_Sales_2023"
  ],
  "recipient": {
    "type": "ServicePrincipal",
    "principalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenantId": "c51dc03f-268a-4da0-a879-25f24947ab8b"
  }
}

Resposta da amostra

Código de estado:
201 
Location: https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/items/5b218778-e7a5-4d73-8187-f10824047715/externalDataShares/dccc162f-7a41-4720-83c3-5c7e81187959
{
  "id": "dccc162f-7a41-4720-83c3-5c7e81187959",
  "paths": [
    "Files/Sales/Contoso_Sales_2023"
  ],
  "creatorPrincipal": {
    "id": "f3052d1c-61a9-46fb-8df9-0d78916ae041",
    "type": "User"
  },
  "recipient": {
    "type": "ServicePrincipal",
    "principalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenantId": "c51dc03f-268a-4da0-a879-25f24947ab8b"
  },
  "status": "Pending",
  "expirationTimeUtc": "2024-12-13T00:00:00.000Z",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "itemId": "5b218778-e7a5-4d73-8187-f10824047715",
  "invitationUrl": "https://app.fabric.microsoft.com/externaldatasharing/accept?providerTenantId=34f92457-fe9d-4c36-92a8-499fdfaf0f8f&shareId=dccc162f-7a41-4720-83c3-5c7e81187959"
}

Definições

Name Description
CreateExternalDataShareRequest

A carga útil da solicitação para criar um compartilhamento de dados externo.
EntireTenantPrincipal

Representa um principal inquilino
ErrorRelatedResource

O objeto de detalhes do recurso relacionado ao erro.
ErrorResponse

A resposta de erro.
ErrorResponseDetails

Os detalhes da resposta de erro.
ExternalDataShare

Um objeto de compartilhamento de dados externo.
ExternalDataShareRecipientType

O tipo de destinatário da partilha externa de dados. Por defeito é 'Utilizador' se não for fornecido. Podem ser adicionados tipos adicionais de destinatários ao longo do tempo.
ExternalDataShareSPRecipient

Um destinatário externo de partilha de dados que é um principal de serviço, identificado pelo principal ID e pelo ID do inquilino.
ExternalDataShareStatus

O status de um determinado compartilhamento de dados externos. Tipos de ExternalDataShareStatus adicionais podem ser adicionados ao longo do tempo.
ExternalDataShareUserRecipient

Um destinatário externo de partilha de dados que é um utilizador, identificado pelo nome principal do utilizador (endereço de email). Este é o tipo de destinatário padrão.
GroupDetails

Detalhes específicos do grupo. Aplicável quando o tipo principal é Group.
GroupPrincipal

Representa um grupo de segurança.
GroupType

O tipo do grupo. Tipos de grupo adicionais podem ser adicionados ao longo do tempo.
PrincipalType

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.
ServicePrincipalDetails

Detalhes específicos da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipal.
ServicePrincipalPrincipal

Representa um principal de serviço Microsoft Entra.
ServicePrincipalProfileDetails

Detalhes do perfil da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipalProfile.
ServicePrincipalProfilePrincipal

Representa um perfil de principal de serviço.
UserDetails

Detalhes específicos principais do usuário. Aplicável quando o tipo principal é User.
UserPrincipal

Representa um principal utilizador do Microsoft Entra.

CreateExternalDataShareRequest

Object

A carga útil da solicitação para criar um compartilhamento de dados externo.

Name Tipo Description
paths

string[]

O caminho ou lista de caminhos que devem ser compartilhados externamente. Você pode compartilhar até 100 caminhos em cada compartilhamento. Um caminho válido para um compartilhamento de dados externo deve começar com "Arquivos/" ou "Tabelas/". Você não pode compartilhar a pasta raiz em si (Arquivos ou Tabelas).

Por exemplo, estes caminhos são válidos:

  • "Files/MyFolder1"

  • "Tabelas/MySchema"

  • "Tables/MyTable1"
recipient BaseExternalDataShareRecipient:

O destinatário convidado a aceitar o compartilhamento de dados externos.

EntireTenantPrincipal

Object

Representa um principal inquilino

Name Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

O ID da entidade de segurança.
type string:

EntireTenant

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

ErrorRelatedResource

Object

O objeto de detalhes do recurso relacionado ao erro.

Name Tipo Description
resourceId

string

A ID do recurso envolvida no erro.
resourceType

string

O tipo de recurso envolvido no erro.

ErrorResponse

Object

A resposta de erro.

Name Tipo Description
errorCode

string

Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
isRetriable

boolean

Quando confirmado, o pedido pode ser retentado. Use o Retry-After cabeçalho de resposta para determinar o atraso, se disponível.
message

string

Uma representação legível por humanos do erro.
moreDetails

ErrorResponseDetails[]

Lista de detalhes de erro adicionais.
relatedResource

ErrorRelatedResource

Os detalhes do recurso relacionados ao erro.
requestId

string (uuid)

ID da solicitação associada ao erro.

ErrorResponseDetails

Object

Os detalhes da resposta de erro.

Name Tipo Description
errorCode

string

Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
message

string

Uma representação legível por humanos do erro.
relatedResource

ErrorRelatedResource

Os detalhes do recurso relacionados ao erro.

ExternalDataShare

Object

Um objeto de compartilhamento de dados externo.

Name Tipo Description
acceptedByTenantId

string (uuid)

O ID do locatário no qual o compartilhamento de dados externos foi aceito.
creatorPrincipal Principal:

A entidade de segurança que criou o compartilhamento de dados externos.
expirationTimeUtc

string (date-time)

A data e hora de expiração (UTC) do convite para o compartilhamento de dados externos.
id

string (uuid)

O ID de compartilhamento de dados externos.
invitationUrl

string (uri)

A URL para aceitar o convite para o compartilhamento de dados externos.
itemId

string (uuid)

O ID do item.
paths

string[]

O caminho ou lista de caminhos que são compartilhados externamente.
recipient BaseExternalDataShareRecipient:

O destinatário que foi convidado a aceitar o compartilhamento de dados externos.
status

ExternalDataShareStatus

O status do compartilhamento de dados externos.
workspaceId

string (uuid)

O ID do espaço de trabalho.

ExternalDataShareRecipientType

Enumeração

O tipo de destinatário da partilha externa de dados. Por defeito é 'Utilizador' se não for fornecido. Podem ser adicionados tipos adicionais de destinatários ao longo do tempo.

Valor Description
ServicePrincipal

O destinatário é um principal de serviço, identificado por ID de objeto e ID de inquilino.
User

O destinatário é um utilizador, identificado pelo nome principal do utilizador (endereço de email). Este é o valor padrão.

ExternalDataShareSPRecipient

Object

Um destinatário externo de partilha de dados que é um principal de serviço, identificado pelo principal ID e pelo ID do inquilino.

Name Tipo Default value Description
principalId

string (uuid)

O ID principal do destinatário principal do serviço. Isto é equivalente ao ID de objeto Entra ID.
tenantId

string (uuid)

O ID do inquilino do destinatário principal do serviço.
type string:

ServicePrincipal

User

O tipo de destinatário da partilha externa de dados. Por defeito é 'Utilizador' se não for fornecido. Podem ser adicionados tipos adicionais de destinatários ao longo do tempo.

ExternalDataShareStatus

Enumeração

O status de um determinado compartilhamento de dados externos. Tipos de ExternalDataShareStatus adicionais podem ser adicionados ao longo do tempo.

Valor Description
Pending

Foi criado um convite que está agora pendente de aceitação por parte do destinatário.
Active

O convite foi aceito pelo destinatário e o compartilhamento de dados externos está ativo.
Revoked

O compartilhamento de dados externos foi revogado.
InvitationExpired

O convite expirou e não pode mais ser aceito pelo destinatário.

ExternalDataShareUserRecipient

Object

Um destinatário externo de partilha de dados que é um utilizador, identificado pelo nome principal do utilizador (endereço de email). Este é o tipo de destinatário padrão.

Name Tipo Default value Description
tenantId

string (uuid)

O ID do locatário do utilizador destinatário. Opcional.
type string:

User

User

O tipo de destinatário da partilha externa de dados. Por defeito é 'Utilizador' se não for fornecido. Podem ser adicionados tipos adicionais de destinatários ao longo do tempo.
userPrincipalName

string

maxLength: 256

O nome principal do utilizador (endereço de email) do destinatário.

GroupDetails

Object

Detalhes específicos do grupo. Aplicável quando o tipo principal é Group.

Name Tipo Description
groupType

GroupType

O tipo do grupo. Tipos de grupo adicionais podem ser adicionados ao longo do tempo.

GroupPrincipal

Object

Representa um grupo de segurança.

Name Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
groupDetails

GroupDetails

Detalhes específicos do grupo. Aplicável quando o tipo principal é Group.
id

string (uuid)

O ID da entidade de segurança.
type string:

Group

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

GroupType

Enumeração

O tipo do grupo. Tipos de grupo adicionais podem ser adicionados ao longo do tempo.

Valor Description
Unknown

O tipo de grupo principal é desconhecido.
SecurityGroup

Principal é um grupo de segurança.
DistributionList

Principal é uma lista de distribuição.

PrincipalType

Enumeração

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

Valor Description
User

Principal é uma entidade de usuário do Microsoft Entra.
ServicePrincipal

Principal é uma entidade de serviço do Microsoft Entra.
Group

Principal é um grupo de segurança.
ServicePrincipalProfile

Principal é um perfil de entidade de serviço.
EntireTenant

Principal representa todos os usuários locatários.

ServicePrincipalDetails

Object

Detalhes específicos da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipal.

Name Tipo Description
aadAppId

string (uuid)

O Microsoft Entra AppId da entidade de serviço.

ServicePrincipalPrincipal

Object

Representa um principal de serviço Microsoft Entra.

Name Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

O ID da entidade de segurança.
servicePrincipalDetails

ServicePrincipalDetails

Detalhes específicos da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipal.
type string:

ServicePrincipal

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

ServicePrincipalProfileDetails

Object

Detalhes do perfil da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipalProfile.

Name Tipo Description
parentPrincipal Principal:

A entidade principal do perfil da entidade de serviço.

ServicePrincipalProfilePrincipal

Object

Representa um perfil de principal de serviço.

Name Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

O ID da entidade de segurança.
servicePrincipalProfileDetails

ServicePrincipalProfileDetails

Detalhes do perfil da entidade de serviço. Aplicável quando o tipo principal é ServicePrincipalProfile.
type string:

ServicePrincipalProfile

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.

UserDetails

Object

Detalhes específicos principais do usuário. Aplicável quando o tipo principal é User.

Name Tipo Description
userPrincipalName

string

O nome principal do usuário.

UserPrincipal

Object

Representa um principal utilizador do Microsoft Entra.

Name Tipo Description
displayName

string

O nome de exibição da entidade de segurança.
id

string (uuid)

O ID da entidade de segurança.
type string:

User

O tipo do principal. Ao longo do tempo, podem ser acrescentados tipos principais adicionais.
userDetails

UserDetails

Detalhes específicos principais do usuário. Aplicável quando o tipo principal é User.