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

  • Artículo

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 se centra en ayudarlo a comenzar a usar PowerShell con la API web de Dataverse en Visual Studio Code. Visual Studio Code con PowerShell proporciona una alternativa a usar Postman con la API web de Dataverse.

En este inicio rápido aprenderá a:

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

Nota

Este artículo de inicio rápido solo presenta conceptos básicos. Esto debería ser suficiente para las pruebas básicas. Después de completar los pasos de este artículo, vaya a Usar PowerShell y Visual Studio Code con la API web de Dataverse para obtener más información. capacidades avanzadas que lo harán más productivo, como por ejemplo:

Las instrucciones de este artículo deberían funcionar para Windows, Linux y macOS, pero estos pasos solo se han probado en Windows. Si se necesitan cambios, háganoslo saber utilizando la sección Comentario al final de este artículo.

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

Verificar instalación

  1. Abra 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 de lenguaje de scripting PowerShell

Pruébelo

  1. En Visual Studio Code, seleccione Archivo > Nuevo archivo de texto, o Control+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
$token = (Get-AzAccessToken -ResourceUrl $environmentUrl).Token
# 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. Pulse F5, o use el comando del 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": "639dea3c-505c-4c3a-b8b5-d916cb507e1e",
"UserId": "d2159662-498a-406b-83cd-f515b7e561d6",
"OrganizationId": "83e197ed-ede1-4886-81f2-f41fe9395297"
}

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

  7. Pulse F5, o use el comando del menú de Visual Studio Code Ejecutar > Iniciar depuración para ejecutar el script de nuevo.

    Debido a que ya inició sesión, la ventana del navegador 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 ha iniciado sesión, este comando devuelve un error. Este script utiliza el parámetro -ErrorAction SilentlyContinue para ignorar el error y no se devuelve nada.

Cuando el comando Get-AzTenant no devuelve nada, la secuencia de comandos utiliza Connect-AzAccount para abrir una ventana interactiva del navegador donde puede ingresar 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.

Finalmente, el script usa el comando Get-AzAccessToken con -ResourceUrl $environmentUrl para obtener una instancia de PSAccessToken, que contiene una propiedad de cadena Token que es un token de acceso que puede usar para autenticar con Dataverse.

Cuando desee conectarse con un conjunto diferente de credenciales, deberá utilizar el comando Disconnect-AzAccount.

Autenticar usando diferentes entornos de shell

Azure PowerShell funciona con entornos de shell de Windows PowerShell y PowerShell, pero no con entornos de shell Cmd y Bash. Si desea autenticarse con entornos de shell Cmd o Bash, puede usar la CLI de Azure.

Este script usa comandos de la CLI de Azure para autenticar:

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## <a name="login-if-not-already-logged-in"></a>Login if not already logged in
if ($null -eq (az account tenant list  --only-show-errors)) {
   az login --allow-no-subscriptions | Out-Null
}
# <a name="get-token"></a>Get token
$token = az account get-access-token --resource=$environmentUrl --query accessToken --output tsv

Esta tabla muestra los comandos equivalentes de Az PowerShell y Azure CLI:

Az PowerShell CLI de Azure Descripción
Get-AzTenant az account tenant list Intente recuperar una lista de inquilinos para detectar si ya ha iniciado sesión
Connect-AzAccount az login Para iniciar sesión en Azure
Get-AzAccessToken az account get-access-token Obtener nuevo token de acceso
Disconnect-AzAccount az logout Cerrar sesión de Azure

Usar Invoke-RestMethod con la función WhoAmI

Una vez que tenga token de acceso configurado en la variable $token, debe redactar la solicitud a la API web de Dataverse y enviarla mediante el cmdlet Invoke-RestMethod.

Establecer encabezados

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

# <a name="common-headers"></a>Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}

Envíe 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 la API web

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

# <a name="invoke-whoami-function"></a>Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

Para operaciones que utilizan métodos HTTP POST o PATCH , configure el uso del parámetro Body para enviar la carga útil 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 propiedad UserId de la respuesta, puede utilizar el siguiente script:

# <a name="get-userid"></a>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 son situaciones que pueden provocar que las instrucciones de este inicio rápido fallen:

No pasa nada cuando pulso F5

Asegúrese de que las teclas de función estén habilitadas en su teclado presionando F-Lock, Fn Lock, o Tecla de bloqueo de funciones en su teclado.

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

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 navegador sea la cuenta que tiene acceso al entorno Dataverse especificado por el parámetro $environmentUrl.

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

Cuando ejecuta el script por primera vez e inicia sesión con el navegador, 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 ignorar esta advertencia si la ve. 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:

Use PowerShell y Visual Studio Code con la API web de Dataverse

Ahora que tiene la capacidad de autenticar y enviar solicitudes de API web de Dataverse mediante PowerShell, puede probar 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.

Tipos y operaciones de API web