Endpoints

Los endpoints se definen por su URI y su método HTTP. Las llamadas realizadas al servidor Universal que coincidan con el endpoint de API y el método definidos ejecutan el script del endpoint de API.

New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint {
   "Hello, world!"
}

Para invocar el método anterior, puede utilizar Invoke-RestMethod.

Invoke-RestMethod http://localhost:5000/endpoint

Al definir endpoints en la API de gestión, puede omitir la llamada a New-PSUEndpoint, ya que la consola de administración la define.

Propiedades de la API

El único contenido que debe proporcionar en el editor es el script que desea llamar.

Contenido de la API

Evite utilizar URL de endpoint que coincidan con las URL internas de la API de gestión de PowerShell Universal, ya que esto provoca un comportamiento inesperado. Puede consultar la documentación de OpenAPI de la API de gestión para verificar que ninguna de las URL coincide.

Métodos HTTP

Los endpoints pueden tener uno o varios métodos HTTP definidos. Para determinar qué método utiliza un endpoint, use la variable integrada $Method.

New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint {
    if ($Method -eq 'GET')
    {
       Get-User
    }
    else {
       New-User
    }
}

URL variable

Las URL pueden contener segmentos variables. Puede indicar un segmento variable mediante dos puntos (:). Por ejemplo, la siguiente URL proporcionaría una variable para el ID del usuario. La variable $Id se definirá dentro del endpoint cuando este se ejecute. Las variables deben ser únicas dentro de la misma URL de endpoint.

New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint {
   Get-User -Id $Id
}

Para llamar a esta API y especificar el ID, haga lo siguiente:

Invoke-RestMethod http://localhost:5000/user/123

Parámetros de cadena de consulta

Los parámetros de cadena de consulta se pasan automáticamente a los endpoints como variables a las que luego puede acceder. Por ejemplo, si tiene un endpoint que espera una variable $Id, puede proporcionarla en la cadena de consulta.

New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint {
   Get-User -Id $Id
}

La llamada resultante a Invoke-RestMethod debe incluir entonces el parámetro de cadena de consulta.

Invoke-RestMethod http://localhost:5000/user?Id=123

Cuando utilice varios parámetros de cadena de consulta, asegúrese de que la URL esté entre comillas para que PowerShell la interprete correctamente. Incluir un ampersand (&) sin comillas causará problemas tanto en Windows PowerShell como en PowerShell 7.

Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim"

Consideraciones de seguridad

Al aceptar entradas mediante parámetros de cadena de consulta, puede ser vulnerable a CWE-914: Improper Control of Dynamically-Identified Variables. Considere utilizar un bloque param para asegurarse de que solo se proporcionen parámetros válidos al endpoint.

A continuación se muestra un ejemplo de CWE-914. Incluya un parámetro de cadena de consulta $IsChallengePassed para omitir el desafío.

New-PSUEndpoint -Url "/api/v1.0/CWE914Test" -Description "Vulnerable to CWE-914" -Endpoint {
	if($ChallengeInputData -eq "AcceptableInput") {
		$IsChallengePassed = $true
	}
	if($IsChallengePassed) {
		"Challenge passed. Here is Sensitive Information"
	} else {
		"Challenge not passed"
	}
}

Para evitar este problema en concreto, puede utilizar un bloque param.

New-PSUEndpoint -Url "/api/v1.0/CWE914Test" -Description "Not Vulnerable to CWE-914" -Endpoint {
	Param(
		$ChallengeInputData
	)
	if($ChallengeInputData -eq "AcceptableInput") {
		$IsChallengePassed = $true
	}
	if($IsChallengePassed) {
		"Challenge passed. Here is Sensitive Information"
	} else {
		"Challenge not passed"
	}
}

Cabeceras

Las cabeceras de solicitud están disponibles en las API mediante la variable $Headers. La variable es una tabla hash. Para acceder a una cabecera, utilice la siguiente sintaxis:

$Headers['Content-Type']

Cookies

Las cookies de solicitud están disponibles en las API mediante la variable $Cookies. La variable es una tabla hash. Para acceder a una cookie, utilice la siguiente sintaxis:

$Cookies['Request-Cookie']

Devuelva las cookies de solicitud con el cmdlet New-PSUApiResponse. Utilice el parámetro -Cookies con una tabla hash proporcionada.

New-PSUApiResponse -StatusCode 200 -Cookies @{
    ResponseCookie = '123'
}

Cuerpo

Para acceder al cuerpo de una solicitud, simplemente accederá a la variable $Body. En Universal, la variable $Body será una cadena. Si espera JSON, debe utilizar ConvertFrom-Json.

New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
    $User = ConvertFrom-Json $Body 
    New-User $User
}

Para llamar al endpoint anterior, especifique el cuerpo de Invoke-RestMethod.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}"

Registro en directo

Puede ver la información del registro en directo de cualquier endpoint haciendo clic en la pestaña de registro. Los registros en directo incluyen la URL, el método HTTP, la dirección IP de origen, los flujos de PowerShell, el código de estado, el Content Type devuelto y la longitud del contenido HTTP.

Puede escribir en el registro en directo desde dentro de sus endpoints con cmdlets como Write-Host.

Registro en directo del endpoint

Pruebas

Puede utilizar la pestaña Test del editor de endpoints para probar sus API. Con esta herramienta de prueba, puede ajustar las cabeceras, la cadena de consulta y el cuerpo. También puede ajustar la Autenticación y la Autorización para la prueba.

Pestaña Test del endpoint

Al utilizar la pestaña de prueba, cualquier cambio en los valores de la prueba dará lugar a un bloque de código actualizado que podrá utilizar después en PowerShell. Haga clic en la pestaña Code para ver el código de prueba.

Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST'

Además, las pruebas realizadas con el probador se almacenarán durante 30 días para permitir volver a probar sin tener que reconfigurar todas las propiedades. Al hacer clic en el botón Apply se configurará la herramienta de prueba con las mismas propiedades.

Historial de pruebas

Datos de formulario

Puede pasar datos a un endpoint como datos de formulario. Los datos de formulario se pasarán a su endpoint como parámetros.

New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
    param([Parameter(Mandatory)]$userName, $FirstName, $LastName)
     
    New-User $UserName -FirstName $FirstName -LastName $LastName
}

Después puede utilizar una tabla hash con Invoke-RestMethod para pasar los datos de formulario.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ 
    UserName = "adriscoll"
    FirstName = "Adam"
    LastName = "Driscoll"
}

Datos JSON

Puede pasar datos JSON a un endpoint y se enlazarán automáticamente a un bloque param.

New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
    param([Parameter(Mandatory)]$userName, $FirstName, $LastName)
     
    New-User $UserName -FirstName $FirstName -LastName $LastName
}

Después puede enviar datos JSON al endpoint.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ 
    UserName = "adriscoll"
    FirstName = "Adam"
    LastName = "Driscoll"
} | ConvertTo-Json) -ContentType 'application/json'

Bloque param

Puede utilizar un bloque param dentro de su script para exigir parámetros obligatorios y proporcionar valores predeterminados para parámetros opcionales, como los parámetros de cadena de consulta. Variables como $Body, $Headers y $User se proporcionan automáticamente.

En el ejemplo siguiente, el parámetro $Name es obligatorio y el parámetro $Role tiene un valor predeterminado de Default.

New-PSUEndpoint -Url '/user/:name' -Endpoint {
    param([Parameter(Mandatory)$Name, $Role = "Default")
}

Cuando utilice el bloque param con parámetros de ruta como en el ejemplo anterior, debe incluir la variable de ruta en su parámetro. Si no se especifica, no tendrá acceso a ese valor.

Por ejemplo, la siguiente variable $Name siempre es $null. El endpoint siempre devuelve false.

New-PSUEndpoint -Url '/user/:name' -Endpoint {
    param($Role = "Default")
    
    $Name -eq 'Adam'
}

Si utiliza el atributo CmdletBinding o Parameter dentro de su bloque param, el endpoint aplicará estrictamente qué parámetros se permiten en el endpoint.

Por ejemplo, lo siguiente exige que se especifique el parámetro name.

New-PSUEndpoint -Url '/user' -Endpoint {
    param([Parameter(Mandatory)$Name)
}

Dicho esto, no puede especificar parámetros adicionales al endpoint. Hacer lo siguiente provocará un error.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ 
    Name = "adriscoll"
    DisplayName = 'Adam'
} | ConvertTo-Json) -ContentType 'application/json'

Si cambia su endpoint para evitar utilizar el atributo Parameter, puede pasar cualquier número de parámetros y se enlazarán como variables y no como parámetros del endpoint.

New-PSUEndpoint -Url '/user' -Endpoint {
    param($Name)
}

Conjuntos de parámetros de método

Puede definir conjuntos de parámetros utilizando parámetros de método. De forma predeterminada, PowerShell Universal inspeccionará el bloque param para determinar si se especifican los nombres de método HTTP Get, Put, Post, Delete u otros, y los incluirá automáticamente. Cuando los endpoints aceptan varios métodos, puede que no sea capaz de determinar qué conjunto de parámetros llamar en función de los datos proporcionados. En el ejemplo siguiente, tanto Get como Post aceptan el parámetro name. Además, no hay forma de llamar a Post sin un name, por lo que la validación podría fallar.

Para solucionar esto, incluya parámetros Post y Get que formen parte de sus respectivos conjuntos de parámetros. PowerShell Universal incluirá este parámetro para garantizar que se llame al conjunto de parámetros adecuado.

New-PSUEndpoint -Url '/user' -Method @("Get", "Post") -Endpoint {
    param(
       [Parameter(ParameterSetName = "GET")]
       [Parameter(ParameterSetName = "POST", Mandatory)]
       $Name,
       [Parameter(ParameterSetName = "GET")]
       [Switch]$Get,
       [Parameter(ParameterSetName = "POST")]
       [Switch]$Post
    )
    
    if ($Get) {
       # Get User
    } 
    
    if ($Post) {
       # Create User
    }
}

Devolución de datos

Se asume que los datos devueltos por los endpoints son datos JSON. Si devuelve un objeto desde el bloque de script del endpoint, se serializa automáticamente a JSON. Si desea devolver otro tipo de datos, puede devolver una cadena con el formato que elija.

Procesamiento de ficheros

Subida de ficheros

Puede procesar los ficheros subidos utilizando el parámetro $Data para acceder a la matriz de bytes de los datos subidos al endpoint.

New-PSUEndpoint -Url '/file' -Method Post -Endpoint {
    $Data
}

PS C:\Users\adamr> iwr http://localhost:5000/file -method post -InFile '.\Desktop\add-dashboard.png'

StatusCode        : 200
StatusDescription : OK
Content           : [137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,2,17,0,0,1,92,8,2,0,0,0,249,210,123,106,0,0,0,1,
                    115,82,71,66,0,174,206,28,233,0,0,0,4,103,65,77,65,0,0,177,143,11,252,97,5,0,0,0,9,112,72,89,115,0,
                    0,…

El tipo de contenido The multipart/form-data no es compatible para subir ficheros a las API.

También puede guardar el fichero en un directorio.

New-PSUEndpoint -Url '/file' -Method Post -Endpoint {
    [IO.File]::WriteAllBytes("tempfile.dat", $Data)
}

Descarga de ficheros

Puede enviar ficheros utilizando el cmdlet New-PSUApiResponse.

New-PSUEndpoint -Url '/image' -Endpoint {
    $ImageData = [IO.File]::ReadAllBytes("image.jpeg")
    New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData
}

Devolución de respuestas personalizadas

Puede devolver respuestas personalizadas desde los endpoints utilizando el cmdlet New-PSUApiResponse en su endpoint. Este cmdlet le permite establecer el código de estado, el tipo de contenido e incluso especificar los datos byte[] del contenido que se va a devolver.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -StatusCode 410
}

También puede devolver datos de cuerpo personalizados con el parámetro -Body de New-PSUApiResponse.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404
}

Al invocar el método REST se devuelve el código de error personalizado.

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file

Invoke-RestMethod: Not what you're looking for.

Puede controlar el tipo de contenido de los datos devueltos con el parámetro -ContentType.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -Body "<xml><node>1</node><node2>2</node2></xml>" -ContentType 'text/xml'
}

Puede controlar las cabeceras de respuesta con una tabla hash de valores que pase al parámetro -Headers.

New-PSUApiResponse -StatusCode 200 -Headers @{
    "Referrer-Policy" = "no-referrer"
}

Runspaces persistentes

Los runspaces persistentes le permiten mantener el estado del runspace entre llamadas a la API. Esto es importante para los usuarios que realizan algún tipo de inicialización dentro de sus endpoints y que no desean ejecutarla en llamadas posteriores a la API.

De forma predeterminada, los runspaces se restablecen después de cada ejecución. Esto elimina las variables, módulos y funciones definidos durante la ejecución de la API.

Para habilitar los runspaces persistentes, deberá configurar un entorno para su API. Establezca el parámetro -PersistentRunspace para habilitar esta función. Esto se configura en el script environments.ps1.

New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace

Después puede asignar el entorno de la API en el script settings.ps1.

Set-PSUSetting -ApiEnvironment 'Env'

Tiempo de espera

De forma predeterminada, los endpoints no agotan el tiempo de espera. Para establecer un tiempo de espera para sus endpoints, puede utilizar el parámetro -Timeout de New-PSUEndpoint. El tiempo de espera se establece en número de segundos.

Contenido de endpoint externo

Puede definir la ruta a un fichero de contenido de endpoint externo con el parámetro -Path de New-PSUEndpoint. La ruta es relativa al directorio .universal del repositorio.

El contenido del fichero endpoints.ps1 es entonces este:

New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1"

API de C#

Las API de C# se habilitan como un plugin.

No existe una interfaz de usuario para crear una API de C#, por lo que debe hacerlo mediante ficheros de configuración. Primero, cree un fichero .cs que ejecute su API.

Tendrá acceso a un parámetro request que incluye todos los datos sobre la solicitud de la API.

public class ApiRequest
{
    public long Id;
    public ICollection<KeyValue> Variables;
    public IEnumerable<ApiFile> Files { get; set; };
    public string Url;
    public ICollection<KeyValue> Headers;
    public byte[] Data;
    public int ErrorAction;
    public ICollection<KeyValue> Parameters;
    public string Method;
    public ICollection<KeyValue> Cookies;
    public string ClaimsPrincipal;
    public string ContentType;
}

También tendrá acceso a una propiedad ServiceProvider que le permite acceder a los servicios dentro de PowerShell Universal. Actualmente no están bien documentados, pero a continuación se muestra un ejemplo de reinicio de un dashboard.

var dm = ServiceProvider.GetService(typeof(IDashboardManager));
var dashboard = dm.GetDashboard(1);
dm.Restart(dashboard);

Otros servicios útiles son:

• IDatabase
• IApiService
• IConfigurationService
• IJobService

Puede optar por devolver un ApiResponse desde su endpoint.

return new ApiResponse {
    StatusCode = 404
};

Una vez que haya definido su fichero de endpoint de C#, puede añadirlo editando endpoints.ps1.

New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#'

El servicio PowerShell Universal compila y ejecuta automáticamente los endpoints de C#.

API

• New-PSUEndpoint
• Get-PSUEndpoint
• Remove-PSUEndpoint
• New-PSUApiResponse
• Set-PSUSetting

Véase también

• Devolutions Academy – Adding reset user password
• Devolutions Academy – User status/refresh user details
• Devolutions Academy – Adding user unlock feature
• Devolutions Academy – Creating a variable endpoint
• Devolutions Academy – Creating a query string endpoint