Edit

Bagikan melalui

Web API Functions and Actions Sample (PowerShell)

This PowerShell version 7.4.0 sample demonstrates how to call bound and unbound functions and actions, including custom actions, using the Microsoft Dataverse Web API. This sample implements the Dataverse operations and console output detailed in Web API Functions and Actions Sample.

View this sample on Github

This sample uses the Dataverse Web API PowerShell Helper functions to manage authentication and provide reusable functions to perform common operations. These scripts are referenced using dot sourcing with the following lines:

. $PSScriptRoot\..\Core.ps1
. $PSScriptRoot\..\TableOperations.ps1
. $PSScriptRoot\..\CommonFunctions.ps1

Note

This sample should work with Windows, Linux, and macOS, but has only been tested on Windows.

Prerequisites

Before running this sample, you should read these articles that explain concepts and patterns used by these samples:

These articles have the same prerequisites.

Install or verify that the following are installed

Verify installation

  1. Open Visual Studio Code.

  2. In the Terminal menu, select New Terminal.

  3. In Visual Studio Code navigation pane, select the icon for the PowerShell extension.

  4. Copy and paste the following script in the Visual Studio Code terminal window:

    Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString()
Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version

  5. Press Enter. The output should resemble the following:

    PowerShell Version: 7.4.0
PowerShell Az version: 11.1.0

If you don't see results like this, install or update the prerequisites.

You'll also need

  • A valid user account for a Dataverse environment
  • The Url to the Dataverse environment you want to connect to. See View developer resources to learn how to find it. It looks something like this: https://yourorg.crm.dynamics.com/, where yourorg.crm is different.
  • Basic understanding of the PowerShell scripting language

How to run this sample

  1. Clone or download the PowerApps-Samples repository.

  2. Open the FunctionsAndActions.ps1 file using Visual Studio Code

  3. Edit this line to use the URL of the environment you want to connect to:

    Connect 'https://yourorg.crm.dynamics.com/' # change this

  4. (Optional) Set the $deleteCreatedRecords variable to $false if you don't want to delete the records this sample creates.

  5. Press F5 to run the sample.

  6. The first time you run the sample a browser window opens. In the browser window, enter or select the credentials you want to use to authenticate.

To connect as a different user, run the Disconnect-AzAccount command and try again.

Code

The code for this sample is at: PowerApps-Samples/dataverse/webapi/PS/FunctionsAndActions/FunctionsAndActions.ps1

Demonstrates

This sample has nine regions:

Section 1: Unbound Function WhoAmI

Operations: Call the WhoAmI Function to retrieve information about the current user.

Section 2: Unbound Function FormatAddress

Operations:

  • Call the FormatAddress Function with parameters for an address in the United States.
  • Call the same function with parameters for an address in Japan to demonstrate different formatting.

Section 3: Unbound Function InitializeFrom

Operations:

  • Create an account record as the original record.
  • Call the InitializeFrom Function to get data for a new record based on the original.
  • Create a new account record using the data returned from InitializeFrom.

Section 4: Unbound Function RetrieveCurrentOrganization

Operations: Call the RetrieveCurrentOrganization Function to retrieve information about the current organization.

Section 5: Unbound Function RetrieveTotalRecordCount

Operations: Call the RetrieveTotalRecordCount Function to retrieve the total number of records for specified tables.

Section 6: Bound Function IsSystemAdmin custom API

Operations:

  • Detect if the sample_IsSystemAdmin custom API is installed in the organization.
  • If not installed, import the managed solution containing the custom API.
  • Retrieve system user records and test each one using the sample_IsSystemAdmin function to determine if they have the System Administrator security role.

Section 7: Unbound Action GrantAccess

Operations:

  • Create an account record to share.
  • Retrieve an enabled user other than the current user.
  • Use the RetrievePrincipalAccess Function to check the user's access rights.
  • Use the GrantAccess Action to grant additional access rights to the user.
  • Verify the access rights were granted using RetrievePrincipalAccess again.

Section 8: Bound Action AddPrivilegesRole

Operations:

  • Create a security role associated with the current user's business unit.
  • Retrieve the role with expanded privileges to show default privileges.
  • Retrieve information about specific privileges to add to the role.
  • Use the AddPrivilegesRole Action to add privileges to the role.
  • Retrieve the role again to confirm the privileges were added.

Section 9: Delete sample records

Operations: A reference to each record created in this sample was added to a list as it was created. This section loops through that list and deletes each record.

Clean up

By default this sample deletes all the records created in it. If you want to view created records after the sample is completed, change the deleteCreatedRecords variable to false and you'll be prompted to decide if you want to delete the records.

See also

Use the Dataverse Web API
Use Web API functions
Use Web API actions
Quick Start Web API with PowerShell and Visual Studio Code
Use PowerShell and Visual Studio Code with the Dataverse Web API
Web API Samples
Web API Functions and Actions Sample
Web API Functions and Actions Sample (C#)
Web API Functions and Actions Sample (Client-side JavaScript)

  • Last updated on