> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/es/api/endpoints.md). # Endpoints Los endpoints se definen mediante 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. ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } ``` Para invocar el método anterior, puede usar `Invoke-RestMethod`. ```powershell Invoke-RestMethod http://localhost:5000/endpoint ``` Al definir endpoints en la API de administración, puede omitir la llamada a `New-PSUEndpoint`, ya que la consola de administración la define. ![API Properties](/files/97OT4IQ5pGh2XigsxBZk) El único contenido que debe proporcionar en el editor es el script que desea llamar. ![API Content](/files/H8RkV3ya2KWp8OxROLXw) {% hint style="warning" %} Evite usar URLs de endpoint que coincidan con las URLs internas de la API de administración de PowerShell Universal, ya que esto provoca un comportamiento inesperado. Puede consultar la [documentación de OpenAPI](/powershell-universal/es/api/openapi.md#management-api-documentation) de la [API de administración](/powershell-universal/es/config/management-api.md) para verificar que ninguna de las URLs coincida. {% endhint %} ## 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`. ```powershell New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint { if ($Method -eq 'GET') { Get-User } else { New-User } } ``` ## URL variable Las URLs pueden contener segmentos variables. Puede indicar un segmento variable usando 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 se ejecute. Las variables deben ser únicas en la misma URL de endpoint. ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` Para llamar a esta API y especificar el ID, haga lo siguiente: ```powershell 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 después puede acceder. Por ejemplo, si tiene un endpoint que espera una variable `$Id`, puede proporcionarla en la cadena de consulta. ```powershell 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. ```powershell 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. ```powershell 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](https://cwe.mitre.org/data/definitions/914.html). Considere usar un bloque `param` para garantizar 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 la comprobación. ```powershell 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 usar un bloque `param`. ```powershell 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 APIs mediante la variable `$Headers`. La variable es una tabla hash. Para acceder a una cabecera, use la siguiente sintaxis: ```powershell $Headers['Content-Type'] ``` ## Cookies Las cookies de solicitud están disponibles en las APIs mediante la variable `$Cookies`. La variable es una tabla hash. Para acceder a una cookie, use la siguiente sintaxis: ```powershell $Cookies['Request-Cookie'] ``` Devuelva cookies de solicitud con el cmdlet `New-PSUApiResponse`. Use el parámetro `-Cookies` con una tabla hash proporcionada. ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` ## Cuerpo Para acceder al cuerpo de una solicitud, simplemente acceda a la variable `$Body`. En Universal, la variable `$Body` será una cadena. Si espera JSON, debería usar `ConvertFrom-Json`. ```powershell 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`. ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}" ``` ## Registro en vivo Puede ver la información del registro en vivo de cualquier endpoint haciendo clic en la pestaña de registro. Los registros en vivo 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 vivo desde sus endpoints con cmdlets como `Write-Host`.

Registro en vivo del endpoint

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

Pestaña Test del endpoint

Al usar la pestaña Test, cualquier cambio en los valores de la prueba dará lugar a un bloque de código actualizado que después puede usar en PowerShell. Haga clic en la pestaña Code para ver el código de la prueba. ```powershell Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST' ``` Además, las pruebas realizadas dentro del 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, la herramienta de pruebas se configurará 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. ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` A continuación puede usar una tabla hash con Invoke-RestMethod para pasar datos de formulario. ```powershell 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. ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` A continuación puede enviar datos JSON al endpoint. ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } | ConvertTo-Json) -ContentType 'application/json' ``` ## Bloque param Puede usar 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 el valor predeterminado Default. ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param([Parameter(Mandatory)$Name, $Role = "Default") } ``` Cuando use 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. ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param($Role = "Default") $Name -eq 'Adam' } ``` Si usa 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. ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param([Parameter(Mandatory)$Name) } ``` Dicho esto, no puede especificar parámetros adicionales al endpoint. Hacer lo siguiente causará un error. ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ Name = "adriscoll" DisplayName = 'Adam' } | ConvertTo-Json) -ContentType 'application/json' ``` Si cambia su endpoint para evitar el uso del atributo `Parameter`, puede pasar cualquier número de parámetros y se enlazarán como variables y no como parámetros del endpoint. ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` ### Conjuntos de parámetros de método Puede definir conjuntos de parámetros usando parámetros de método. De forma predeterminada, PowerShell Universal inspeccionará el bloque param para determinar si se especifican estos nombres de método HTTP `Get`, `Put`, `Post`, `Delete` u otros, y los incluirá automáticamente. Cuando los endpoints aceptan varios métodos, puede no ser capaz de determinar qué conjunto de parámetros llamar según 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 solucionarlo, 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. {% code overflow="wrap" %} ```powershell 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 } } ``` {% endcode %} ## Devolver 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. ## Procesar ficheros ### Subir ficheros Puede procesar los ficheros subidos usando el parámetro `$Data` para acceder a la matriz de bytes de los datos subidos al endpoint. ```powershell 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,… ``` {% hint style="warning" %} El tipo de contenido `The multipart/form-data`no se admite para subir ficheros a las APIs. {% endhint %} También puede guardar el fichero en un directorio. ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` ### Descargar ficheros Puede enviar ficheros usando el cmdlet `New-PSUApiResponse`. ```powershell New-PSUEndpoint -Url '/image' -Endpoint { $ImageData = [IO.File]::ReadAllBytes("image.jpeg") New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData } ``` ## Devolver respuestas personalizadas Puede devolver respuestas personalizadas desde los endpoints usando 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. ```powershell 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`. ```powershell 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. ```powershell 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`. ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "12" -ContentType 'text/xml' } ``` Puede controlar las cabeceras de respuesta con una tabla hash de valores que pase al parámetro `-Headers`. ```powershell 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 que no desean ejecutar en las llamadas a la API posteriores. De forma predeterminada, los runspaces se restablecen después de cada ejecución. Esto elimina las variables, los módulos y las funciones definidos durante la ejecución de la API. Para habilitar los runspaces persistentes, deberá configurar un [entorno ](/powershell-universal/es/config/environments.md)para su API. Establezca el parámetro `-PersistentRunspace` para habilitar esta función. Esto se configura en el script `environments.ps1`. ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` A continuación puede asignar el entorno de la API en el script `settings.ps1`. ```powershell Set-PSUSetting -ApiEnvironment 'Env' ``` ## Tiempo de espera De forma predeterminada, los endpoints no expiran. Para establecer un tiempo de espera para sus endpoints, puede usar el parámetro `-Timeout` de `New-PSUEndpoint`. El tiempo de espera se establece en 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: ```powershell New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1" ``` ## APIs de C\# Las APIs de C# se habilitan como un [plugin](/powershell-universal/es/plataforma/plugins.md#c-api-environment). No hay interfaz de usuario para crear una API de C#, por lo que debe hacerlo usando 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. ```csharp public class ApiRequest { public long Id; public ICollection Variables; public IEnumerable Files { get; set; }; public string Url; public ICollection Headers; public byte[] Data; public int ErrorAction; public ICollection Parameters; public string Method; public ICollection 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. ```csharp 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. ```powershell return new ApiResponse { StatusCode = 404 }; ``` Una vez que haya definido su fichero de endpoint de C#, puede añadirlo editando `endpoints.ps1`. ```powershell 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](/powershell-universal/es/comandos-de-powershell/new-psuendpoint.md) * [Get-PSUEndpoint](/powershell-universal/es/comandos-de-powershell/get-psuendpoint.md) * [Remove-PSUEndpoint](/powershell-universal/es/comandos-de-powershell/remove-psuendpoint.md) * [New-PSUApiResponse](/powershell-universal/es/comandos-de-powershell/new-psuapiresponse.md) * [Set-PSUSetting](/powershell-universal/es/comandos-de-powershell/set-psusetting.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/es/api/endpoints.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.