Como conectar seu aplicativo de código aos dados (versão prévia)

Os aplicativos de código permitem a conexão com conectores do Power Platform.

Use as seguintes etapas:

1. Criar e configurar conexões no Power Apps
2. Adicionar uma conexão a um aplicativo de código
3. Atualizar o aplicativo para fazer chamadas por conexão

Criar e configurar conexões no Power Apps

Comece criando e configurando conexões no Power Apps. Copie os metadados de conexão de lá para uso em etapas posteriores.

Os seguintes conectores têm suporte oficial:

• SQL Server
• SharePoint
• Usuários do Office 365
• Grupos do Office 365
• Azure Data Explorer
• OneDrive para trabalho ou escola
• Power Apps para Criadores
• Equipes da Microsoft
• MSN Clima
• Microsoft Translator V2
• Operações de criação, leitura, atualização e exclusão do Dataverse

Espera-se que outros conectores funcionem, mas não são testados.

Lançar a página de Conexões do Power Apps

Acesse o Power Apps e navegue até a página Conexões a partir da navegação à esquerda.

Exemplo: criar uma conexão de usuários do Office 365

Selecione + Nova conexão e selecione Usuários do Office 365. Selecione Criar.

(Opcional) Criar uma conexão SQL (ou uma conexão para outra fonte de dados tabular)

Obter metadados de conexão para todas as conexões criadas

Há duas maneiras de fazer isso:

• Usar a CLI do PAC
• Usar a URL do Power Apps

Usar a CLI do PAC

Use a CLI do Power Apps para listar suas conexões disponíveis e recuperar suas IDs usando o comando pac connection list .

pac connection list exibe uma tabela de todas as suas conexões, incluindo a ID de Conexão e o Nome da API, que é usado como o appId ao adicionar uma fonte de dados.

Usar a URL do Power Apps

Você também pode recuperar essas informações usando o Power Apps exibindo a URL ao examinar os detalhes de uma conexão.

Observe como o nome da API e a ID de conexão são acrescentados à URL:

Copie o nome da API e a ID de conexão da CLI do PAC para a URL de cada conexão.

Adicionar uma conexão a um aplicativo de código

Depois de criar ou identificar conexões existentes a serem usadas e copiar os metadados de conexão da etapa anterior, adicione essas conexões ao aplicativo.

Adicionar as fontes de dados ao aplicativo gera automaticamente um modelo TypeScript digitado e um arquivo de serviço no repositório. Por exemplo, a fonte de dados Usuários do Office 365 produz Office365UsersModel e Office365UsersService.

Adicionar uma fonte de dados nontabular

Adicione uma fonte de dados não tabular (por exemplo, Usuários do Office 365) ao aplicativo usando o comando pac code add-data-source da PAC CLI.

Em uma linha de comando, execute o comando a seguir. Use o nome da API e a ID de conexão coletadas das etapas anteriores.

pac code add-data-source -a <apiName> -c <connectionId>

Por exemplo:

pac code add-data-source -a "shared_office365users" -c "aaaaaaaa000011112222bbbbbbbbbbbb"

Adicionar uma fonte de dados tabular

SQL ou SharePoint são exemplos de fontes de dados tabulares.

Use o mesmo comando pac CLI pac add-data-source, mas inclua o ID da tabela e o nome do conjunto de dados. O esquema da fonte de dados tabular especifica esses valores. Se você ainda não os tiver, consulte Recuperar um nome de conjunto de dados e uma ID da tabela.

pac code add-data-source -a <apiName> -c <connectionId> -t <tableId> -d <datasetName> 

Por exemplo:

pac code add-data-source `
-a "shared_sql" `
-c "aaaaaaaa000011112222bbbbbbbbbbbb" `
-t "[dbo].[MobileDeviceInventory]" `
-d "paconnectivitysql0425.database.windows.net,paruntimedb"

pac code add-data-source `
-a "shared_sql" `
-c "aaaaaaaa000011112222bbbbbbbbbbbb" `
-t "[dbo].[EmployeeInformation]" `
-d "paconnectivitysql0425.database.windows.net,paruntimedb" 

Recuperar um nome de conjunto de dados e uma ID da tabela

Se você ainda não tiver o nome da tabela e do conjunto de dados, poderá obtê-los executando um aplicativo de tela e copiando os valores do inspetor de rede do navegador:

1. Crie um novo aplicativo de tela no Studio.

2. Adicione a conexão a um aplicativo canvas.

3. Associe a conexão a um controle de galeria.

4. Publique e execute o aplicativo.

5. Abra as Ferramentas de Desenvolvedor do navegador, acesse a guia Rede e inspecione as solicitações feitas quando o aplicativo for carregado. Verifique a solicitação "invoke" e vá até a resposta.

6. Localize uma solicitação de APIM (Gerenciamento de API do Azure) com a ID de conexão, o nome do conjunto de dados e a ID da tabela e copie esses valores.

   Usando esta URL de solicitação de dados de exemplo por meio do APIM, procure os valores <Connection ID>, <Dataset name> e <Table ID> nestes locais na URL:

   https[]()://{id value}.01.common.azure-apihub.net/apim/sharepointonline/<Connection ID>/datasets/<Dataset name>/tables/<Table ID>/items
   

Adicionar um procedimento armazenado SQL como uma fonte de dados

Em uma linha de comando, execute o comando a seguir. Use o nome da API e a ID de conexão coletadas anteriormente.

pac code add-data-source -a <apiId> -c <connectionId> -d <dataSourceName> -sp <storedProcedureName> 

Por exemplo:

pac code add-data-source `
–a "shared_sql" `
-c "33dd33ddee44ff55aa6677bb77bb77bb" `
-d "paconnectivitysql0425.database.windows.net,paruntimedb" `
-sp "[dbo].[GetRecordById]" 

Excluir fontes de dados

Se necessário, você pode excluir fontes de dados depois de adicionar.

Em uma linha de comando, execute o comando a seguir. Use o nome da API e a ID de conexão coletadas anteriormente.

pac code delete-data-source -a <apiName> -ds <dataSourceName> 

Por exemplo:

pac code delete-data-source `
-a "shared_sql" `
-ds "MobileDeviceInventory" 

Usar referências de conexão para adicionar uma fonte de dados

A partir da versão 1.51.1 da CLI do Power Apps lançada em dezembro de 2025, você pode usar referências de conexão para adicionar fontes de dados ao seu aplicativo de código. Uma referência de conexão é um componente de solução que aponta para uma conexão específica para um conector. Em vez de associar seu aplicativo diretamente a uma conexão específica do usuário, você o associa a uma referência. Isso torna a solução com reconhecimento de ambiente e portátil em ambientes Dev, Test e Prod para o gerenciamento suave do ciclo de vida do aplicativo.

Obter a ID da solução

Há duas maneiras de obter a ID da sua solução:

Use o comando de lista de soluções da CLI do PAC:

1. Abra um prompt de comando ou uma janela de terminal.

2. Execute o seguinte comando para obter uma lista de soluções no ambiente ao qual você está conectado:

   pac solution list --json | ConvertFrom-Json | Format-Table
   

   Esse comando exibe no console uma tabela com as propriedades da solução Id, SolutionUniqueName e FriendlyName.

3. Copie a solução Id e salve-a para uso posterior.

Use o gerenciador de soluções do Power Apps:

1. Entre no Power Apps.

2. No painel esquerdo, selecione Soluções. Se o item não estiver no painel lateral, selecione Mais e selecione o item desejado.

3. Localize a solução que contém a referência de conexão para sua fonte de dados.

4. Selecione a solução para abri-la.

5. Na URL do navegador, localize a ID da solução no final da URL. Sua URL é do formato:

   https://make.powerapps.com/environments/environmentId/solutions/solutionId
   

6. Copie a ID da solução da URL e salve-a para uso posterior.

Obtenha o nome da referência de conexão para a sua fonte de dados

Há duas maneiras de obter a referência de conexão à fonte de dados:

Utilize o comando 'code' do PAC CLI para listar as referências de conexão em uma solução:

1. Abra um prompt de comando ou uma janela de terminal.

2. Execute o seguinte comando para obter a ID da solução e o nome da referência de conexão à fonte de dados:

    pac code list-connection-references -env <environmentURL> -s <solutionID>
   

3. A saída inclui o nome de exibição, o nome lógico e a descrição das referências de conexão na solução.

Use o gerenciador de soluções do Power Apps para examinar as referências de conexão em uma solução:

1. Entre no Power Apps.
2. No painel esquerdo, selecione Soluções. Se o item não estiver no painel lateral, selecione Mais e selecione o item desejado.
3. Localize a solução que contém a referência de conexão para sua fonte de dados.
4. Selecione Referências de Conexão na lista de Objetos no painel esquerdo.

Adicionar a fonte de dados ao seu aplicativo de código usando a referência de conexão

Em uma linha de comando, execute o comando a seguir. Use o ID da solução e o nome lógico de referência de conexão coletado das etapas anteriores.

pac code add-data-source -a <apiName> -cr <connectionReferenceLogicalName> -s <solutionID>

O aplicativo agora usa a conexão associada à referência de conexão em sua solução do Power Apps.

Atualizar o aplicativo para chamar conexões

Depois que as conexões forem adicionadas, você poderá atualizar o aplicativo para usar o modelo e o serviço gerados.

1. Garantir a inicialização do SDK do Power Apps antes das chamadas de dados

   Em seu App.tsx arquivo, implemente a lógica que aguarda que o SDK do Power Apps seja totalmente inicializado antes de executar quaisquer operações de dados. Isso evita erros causados por serviços não inicializados ou contexto ausente. Isso só precisa ser feito uma vez.

   Use uma função assíncrona ou gerenciamento de estado para confirmar a inicialização antes de fazer chamadas à API. Por exemplo:

   useEffect(() => {
   // Define an async function to initialize the Power Apps SDK
   const init = async () => {
         try {
               await initialize(); // Wait for SDK initialization
               setIsInitialized(true); // Mark the app as ready for data operations
         } catch (err) {
               setError('Failed to initialize Power Apps SDK'); // Handle initialization errors
               setLoading(false); // Stop any loading indicators
         }
   };
   
   init(); // Call the initialization function when the component mounts
   }, []);
   
   useEffect(() => {
   // Prevent data operations until the SDK is fully initialized
   if (!isInitialized) return;
   
   // Place your data reading logic here
   }, []);
   

2. Importar tipos e serviços necessários

   Quando você adiciona uma fonte de dados, os arquivos de modelo e de serviço são gerados e colocados automaticamente na /generated/services/ pasta. Por exemplo, se você adicionar Office365Users como uma fonte de dados, os seguintes arquivos serão criados:

   • Office365UsersModel.ts – Define o modelo de dados para solicitações e objetos de resposta no Office365Users conector.
   • Office365UsersService.ts – Fornece métodos de serviço para interagir com os Office365Users dados.

   Você pode importá-los e usá-los em seu código da seguinte maneira:

   import { Office365UsersService } from './generated/services/Office365UsersService';
   import type { User } from './generated/models/Office365UsersModel';
   

3. Atualize o aplicativo para usar a fonte de dados nontabular (por exemplo, Usuários do Office 365)

   Você pode ver os arquivos gerados nas pastas src/generated/models and src/generated/services para a API de conexão tipada.

   await Office365UsersService.MyProfile() 
   

   const profile = (await Office365UsersService.MyProfile_V2("id,displayName,jobTitle,id,userPrincipalName")).data; 
      setUser(profile); 
      if (profile?.id || profile?.userPrincipalName) { 
         // Try both id and userPrincipalName for photo 
         let photoData = null; 
         try { 
         photoData = (await Office365UsersService.UserPhoto_V2(profile.id || profile.userPrincipalName)).data; 
         } catch { 
         // fallback to userPrincipalName if id fails 
         if (profile.userPrincipalName) { 
            photoData = (await Office365UsersService.UserPhoto_V2(profile.userPrincipalName)).data; 
         } 
         } 
         if (photoData) setPhoto(`data:image/jpeg;base64,${photoData}`); 
   

4. (Opcional) Atualize o aplicativo para usar a fonte de dados tabular (por exemplo, SQL)

   Você pode ver os arquivos gerados nas pastas src/Models e src/Services para a API de conexão tipada.

   Por exemplo:

   await MobileDeviceInventoryService.create(<record>) 
   await MobileDeviceInventoryService.update(id, <record>) 
   await MobileDeviceInventoryService.delete(id) 
   await MobileDeviceInventoryService.get(id) 
   await MobileDeviceInventoryService.getall() 
   

   await MobileDeviceInventoryService.update(assetId, changedFields); 
   setAssets((prevAssets) => 
     prevAssets.map((asset) => { 
       if (asset.id === assetId) { 
   

5. Executar o aplicativo localmente para verificar as alterações

   Use este comando no terminal:

   npm run dev
   

6. Enviar por push o aplicativo para ser executado no Power Apps

   Use o seguinte comando no terminal:

   npm run build | pac code push