Inicio rápido: API web con PowerShell y Visual Studio Code

Aprenda a usar PowerShell con la API web de Dataverse en Visual Studio Code. PowerShell es un potente lenguaje de secuencias de comandos que puede automatizar tareas repetitivas y optimizar los flujos de trabajo, lo que lo convierte en una herramienta ideal para integrarse con Dataverse. Este inicio rápido le ayuda a empezar a usar PowerShell con la API web de Dataverse en Visual Studio Code. Visual Studio Code con PowerShell proporciona una alternativa a usar clientes de API como Postman o Insomnia.

En esta guía de inicio rápido, ha aprendido a hacer lo siguiente:

• Usar Visual Studio Code con PowerShell para autenticarse interactivamente con Dataverse sin registrar una aplicación.
• Componer solicitudes a la API web de Dataverse mediante el cmdlet Invoke-RestMethod de PowerShell.

Requisitos previos

No continúe sin confirmar que se cumple cada uno de los siguientes requisitos previos.

Instale o verifique que lo siguiente esté instalado

• Instale Visual Studio Code. Consulte Descargar Visual Studio Code

• Instalar la extensión de PowerShell para Visual Studio Code. Consulte PowerShell para Visual Studio Code

• Instale PowerShell 7.4 o superior. Consulte Instalar PowerShell en Windows, Linux y macOS

• Instale el módulo Az PowerShell versión 11.1.0 o superior. Consulte Cómo instalar Azure PowerShell

  Para actualizar una instalación existente a la última versión, use Update-Module -Name Az -Force

Verificar instalación

1. Abre Visual Studio Code.

2. En el menú Terminal, seleccione Nueva terminal.

3. En el panel de navegación de Visual Studio Code, seleccione el icono para la extensión de PowerShell.

4. Copie y pegue el script siguiente en la ventana de la terminal de Visual Studio Code:

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

5. Presione Entrar. El resultado debería similar al siguiente:

   PowerShell Version: 7.4.0
   PowerShell Az version: 11.1.0
   

Si no ve resultados como este, instale o actualice los requisitos previos.

También necesitará

• Una cuenta de usuario válida para un entorno de Dataverse
• La dirección URL al entorno de Dataverse al que quiere conectarse. Consulte Ver recursos para desarrolladores para saber cómo encontrarlo. Se parece a esto: https://yourorg.crm.dynamics.com/, donde yourorg.crm es diferente.
• Comprensión básica del lenguaje de scripting de PowerShell

Pruébelo

1. En Visual Studio Code, seleccione Archivo>nuevo archivo de texto o presione Ctrl+N para abrir un archivo nuevo.

   No necesita guardar el archivo.

2. Copie y pegue el siguiente script en el archivo nuevo.

   $environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
   ## Login if not already logged in
   if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) {
      Connect-AzAccount | Out-Null
   }
   
   # Get an access token
   $secureToken = (Get-AzAccessToken `
      -ResourceUrl $environmentUrl `
      -AsSecureString).Token
   
   # Convert the secure token to a string
   $token = ConvertFrom-SecureString `
      -SecureString $secureToken `
      -AsPlainText
   
   
   # Common headers
   $baseHeaders = @{
      'Authorization'    = 'Bearer ' + $token
      'Accept'           = 'application/json'
      'OData-MaxVersion' = '4.0'
      'OData-Version'    = '4.0'
   }
   # Invoke WhoAmI Function
   Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
   | ConvertTo-Json
   

   Visual Studio Code debería detectar automáticamente que es un script de PowerShell.

3. Edite el valor de la variable $environmentUrl (https://yourorg.crm.dynamics.com/) para que coincida con su URL del entorno de Dataverse.

4. Presione F5 o use el comando de menú de Visual Studio Code Ejecutar>Iniciar depuración.

   Se abre una ventana de explorador nueva. En la ventana del navegador, ingrese o seleccione las credenciales que desea usar para autenticarse.

5. Verifique la salida en la ventana de la terminal de Visual Studio Code.

   En la parte inferior de la terminal, busque el valor del tipo complejo WhoAmIResponse esperado para la función WhoAmI. Debería tener aspecto similar a éste:

   {
   "@odata.context": "https://yourorg.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
   "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
   "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
   }
   

6. En la ventana de terminal, escriba cls para borrar el contenido de la terminal.

7. Presione F5 o utilice el comando de menú de Visual Studio Code Ejecutar>Iniciar depuración para ejecutar el script de nuevo.

   Dado que ya está autenticado, la ventana del explorador no se abre. Puede continuar editando y ejecutando su script para probar diferentes solicitudes.

Cómo funciona

Esta sección describe los detalles del script de PowerShell incluido en la sección Pruébelo.

Autenticación

El script usa el comando del módulo Az PowerShell Get-AzTenant para obtener inquilinos autorizados para el usuario actual. Cuando no haya iniciado sesión, este comando devuelve un error. El script usa el -ErrorAction SilentlyContinue parámetro para omitir el error y devolver nada.

Cuando el Get-AzTenant comando no devuelve nada, el script usa el comando Connect-AzAccount para abrir una ventana interactiva del explorador donde puede escribir o seleccionar sus credenciales para iniciar sesión. Obtenga más información sobre cómo iniciar sesión en Azure PowerShell de forma interactiva o no interactiva con una entidad de servicio.

Por último, el script usa el comando Get-AzAccessToken con el parámetro -ResourceUrl $environmentUrl, para obtener una instancia de PSAccessToken, que contiene una propiedad SecureString Token que se puede convertir en un token de acceso para autenticarse con Dataverse.

Cuando quiera conectarse con un conjunto diferente de credenciales, use el comando Disconnect-AzAccount .

Usar Invoke-RestMethod con la función WhoAmI

Después de establecer el token de acceso en la $token variable, redacte la solicitud en Dataverse Web API y envíela mediante el cmdletInvoke-RestMethod.

Establecer encabezados

Todas las solicitudes de API web de Dataverse deben incluir un conjunto de encabezados de solicitud HTTP comunes, incluido un Authorization encabezado que incluya el valor del token de acceso. Algunas operaciones requieren más encabezados de datos. Obtenga más información sobre los encabezados de solicitud de API web de Dataverse.

# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}

Envío de la solicitud

La función WhoAmI es una de las operaciones Dataverse más simples que puede realizar. Debido a que es una función de OData en lugar de una acción, requiere el método HTTP GET. Obtenga más información sobre las funciones de API web.

Utilice los parámetros Invoke-RestMethodUri, Method y Headers para enviar esta solicitud.

# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

En el caso de las operaciones que usan POST o PATCH métodos HTTP, establezca el Body parámetro para enviar la carga JSON.

El cmdlet ConvertTo-Json convierte el objeto devuelto en una cadena con formato JSON que es fácil de ver en la terminal.

Si desea capturar solo la UserId propiedad de la respuesta, use el siguiente script:

# Get UserId
$userId = (
   Invoke-RestMethod `
   -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') `
   -Method 'Get' `
   -Headers $baseHeaders
   ).UserId
Write-Host $userId

Solución de problemas

Asegúrese de verificar que todos los programas necesarios estén instalados como se describe en Verificar instalación.

Las siguientes situaciones pueden provocar un error en las instrucciones de este inicio rápido:

No pasa nada cuando pulso F5

Asegúrese de que el teclado tiene teclas de función habilitadas presionando la tecla F-Lock, Fn Lock o Function Lock .

En su lugar, también puede utilizar el comando de menú de Visual Studio Code Ejecutar>Iniciar depuración.

No se conoce tal anfitrión

Si ve este error después de ejecutar el script:

Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   | No such host is known.

Compruebe que $environmentUrl representa un entorno al que tiene acceso. Asegúrese de haberlo cambiado del valor predeterminado (https://yourorg.crm.dynamics.com/).

El usuario no es miembro de la organización

Si ve este error después de ejecutar el script:

Invoke-RestMethod: untitled:Untitled-1:14:1                                                                             
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   |  {   "error": {     "code": "0x80072560",     "message": "The user is not a member of the organization."   } }

Asegúrese de que la cuenta que seleccione en la ventana del explorador es la cuenta que tiene acceso al entorno de Dataverse especificado por el $environmentUrl parámetro .

Si está utilizando un conjunto de credenciales diferente al que usaba antes, use el comando Disconnect-AzAccount en la ventana del terminal.

ADVERTENCIA: TenantId '<su ID de inquilino>' contiene más de una suscripción activa

Al ejecutar el script por primera vez e iniciar sesión con el explorador, es posible que reciba esta advertencia:

WARNING: TenantId '<your tenant id>' contains more than one active subscription. First one will be selected for further use. 
To select another subscription, use Set-AzContext. 
To override which subscription Connect-AzAccount selects by default, use `Update-AzConfig -DefaultSubscriptionForLogin 00000000-0000-0000-0000-000000000000`. 
Go to https://go.microsoft.com/fwlink/?linkid=2200610 for more information.

Puede omitir esta advertencia. Estas solicitudes no requieren suscripción.

Pasos siguientes

Obtenga más capacidades avanzadas para ser más productivo usando PowerShell y Visual Studio Code con la API web de Dataverse, por ejemplo, cómo:

• Crear funciones reutilizables
• Administrar excepciones
• Administrar límites de protección de servicio de Dataverse
• Corregir errores usando Fiddler
• Descargar el documento $metadata CSDL de la API web de Dataverse

Ahora que puede autenticar y enviar solicitudes de API web de Dataverse mediante PowerShell, pruebe otras operaciones de API web.

Aprender más acerca de las Capacidades de API web de Dataverse mediante la comprensión de los documentos de servicio.