> 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 Configure los endpoints de la API de PowerShell Universal con New-PSUEndpoint, cubriendo el enrutamiento de URL, los encabezados, las cookies, los cuerpos de solicitud, las cargas de ficheros y las re Los endpoints se definen por su URI y su método HTTP. Las llamadas realizadas al servidor Universal que coinciden con el endpoint de API y el método definidos ejecutan el script del endpoint de API. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } ``` {% endcode %} Para invocar el método anterior, puede usar `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/endpoint ``` {% endcode %} 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. El único contenido que debe proporcionar en el editor es el script que desea llamar. {% hint style="warning" %} Evite usar URL de endpoint que coincidan con las URL 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 URL coincida. {% endhint %} ## Métodos HTTP Los endpoints pueden tener uno o varios métodos HTTP definidos. Para determinar qué método usa un endpoint, use la variable integrada `$Method`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint { if ($Method -eq 'GET') { Get-User } else { New-User } } ``` {% endcode %} ## 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 se ejecute. Las variables deben ser únicas en la misma URL de endpoint. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} Para llamar a esta API y especificar el ID, haga lo siguiente: {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user/123 ``` {% endcode %} ## 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} La llamada `Invoke-RestMethod` resultante debe incluir entonces el parámetro de cadena de consulta. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user?Id=123 ``` {% endcode %} Al usar 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. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim" ``` {% endcode %} ### 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 el desafío. {% code collapsedlinecount="10" %} ```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" } } ``` {% endcode %} Para evitar este problema concreto, puede usar un bloque `param`. {% code collapsedlinecount="10" %} ```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" } } ``` {% endcode %} ## Encabezados Los encabezados de solicitud están disponibles en las API mediante la variable `$Headers`. La variable es una tabla hash. Para acceder a un encabezado, use la siguiente sintaxis: {% code collapsedlinecount="10" %} ```powershell $Headers['Content-Type'] ``` {% endcode %} ## 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, use la siguiente sintaxis: {% code collapsedlinecount="10" %} ```powershell $Cookies['Request-Cookie'] ``` {% endcode %} Devuelva las cookies de solicitud con el cmdlet `New-PSUApiResponse`. Use el parámetro `-Cookies` con una tabla hash proporcionada. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` {% endcode %} ## Cuerpo Para acceder al cuerpo de una solicitud, simplemente accederá a la variable `$Body`. La variable `$Body` de Universal será una cadena. Si espera JSON, debe usar `ConvertFrom-Json`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { $User = ConvertFrom-Json $Body New-User $User } ``` {% endcode %} Para llamar al endpoint anterior, especifique el cuerpo de `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}" ``` {% endcode %} ## 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 tipo de contenido devuelto y la longitud del contenido HTTP. Puede escribir en el registro en vivo desde sus endpoints con cmdlets como `Write-Host`. ## Pruebas Puede usar la pestaña Prueba del editor de endpoints para probar sus API. Con esta herramienta de prueba, puede ajustar los encabezados, la cadena de consulta y el cuerpo. También puede ajustar la autenticación y la autorización de la prueba. Al usar la pestaña de prueba, cualquier cambio en los valores de la prueba dará lugar a un bloque de código actualizado que podrá usar en PowerShell. Haga clic en la pestaña Código para ver el código de prueba. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST' ``` {% endcode %} Además, las pruebas realizadas en 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 Aplicar, se configurará la herramienta de prueba con las mismas propiedades. ## 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` {% endcode %} Después puede usar una tabla hash con Invoke-RestMethod para pasar datos de formulario. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } ``` {% endcode %} ## Datos JSON Puede pasar datos JSON a un endpoint y se enlazarán automáticamente a un bloque param. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` {% endcode %} Después puede enviar datos JSON al endpoint. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } | ConvertTo-Json) -ContentType 'application/json' ``` {% endcode %} ## Bloque param Puede usar un bloque `param` en 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param([Parameter(Mandatory)$Name, $Role = "Default") } ``` {% endcode %} Al usar 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param($Role = "Default") $Name -eq 'Adam' } ``` {% endcode %} Si usa el atributo `CmdletBinding` o `Parameter` en 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param([Parameter(Mandatory)$Name) } ``` {% endcode %} Dicho esto, no puede especificar parámetros adicionales al endpoint. Hacer lo siguiente provocará un error. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ Name = "adriscoll" DisplayName = 'Adam' } | ConvertTo-Json) -ContentType 'application/json' ``` {% endcode %} Si cambia su endpoint para evitar usar el atributo `Parameter`, puede pasar cualquier número de parámetros y se enlazarán como variables y no como parámetros del endpoint. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` {% endcode %} ### 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étodos 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 a qué conjunto de parámetros llamar según los datos proporcionados. En el ejemplo siguiente, tanto Get como Post aceptan el parámetro name. Tampoco hay forma de llamar a Post sin un nombre, por lo que la validación podría fallar. Para solucionar esto, incluya los 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" collapsedlinecount="10" %} ```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. ## Procesamiento de ficheros ### Carga de ficheros Puede procesar los ficheros cargados usando el parámetro `$Data` para acceder a la matriz de bytes de los datos cargados en el endpoint. {% code collapsedlinecount="10" %} ```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,… ``` {% endcode %} {% hint style="warning" %} `The multipart/form-data`no se admite como tipo de contenido para cargar ficheros en las API. {% endhint %} También puede guardar el fichero en un directorio. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` {% endcode %} ### Descarga de ficheros Puede enviar ficheros usando el cmdlet `New-PSUApiResponse`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/image' -Endpoint { $ImageData = [IO.File]::ReadAllBytes("image.jpeg") New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData } ``` {% endcode %} ## 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 devolverá. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -StatusCode 410 } ``` {% endcode %} También puede devolver datos de cuerpo personalizados con el parámetro `-Body` de `New-PSUApiResponse`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404 } ``` {% endcode %} Al invocar el método REST se devuelve el código de error personalizado. {% code collapsedlinecount="10" %} ```powershell PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file Invoke-RestMethod: Not what you're looking for. ``` {% endcode %} Puede controlar el tipo de contenido de los datos devueltos con el parámetro `-ContentType`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "12" -ContentType 'text/xml' } ``` {% endcode %} Puede controlar los encabezados de respuesta con una tabla hash de valores que pase al parámetro `-Headers`. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Headers @{ "Referrer-Policy" = "no-referrer" } ``` {% endcode %} ## 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 en sus endpoints que no desean ejecutar en 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`. {% code collapsedlinecount="10" %} ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` {% endcode %} Después puede asignar el entorno de la API en el script `settings.ps1`. {% code collapsedlinecount="10" %} ```powershell Set-PSUSetting -ApiEnvironment 'Env' ``` {% endcode %} ## 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 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: {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1" ``` {% endcode %} ## API de C\# Las API de C# se habilitan como [plugin](/powershell-universal/es/plataforma/plugins/c-api-endpoints.md). No hay interfaz de usuario para crear una API de C#, por lo que debe hacerlo usando ficheros de configuración. En primer lugar, 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. {% code collapsedlinecount="10" %} ```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; } ``` {% endcode %} También tendrá acceso a una propiedad `ServiceProvider` que le permite acceder a los servicios de PowerShell Universal. Actualmente no están bien documentados, pero a continuación se muestra un ejemplo de cómo reiniciar un dashboard. {% code collapsedlinecount="10" %} ```csharp var dm = ServiceProvider.GetService(typeof(IDashboardManager)); var dashboard = dm.GetDashboard(1); dm.Restart(dashboard); ``` {% endcode %} Otros servicios útiles incluyen: * IDatabase * IApiService * IConfigurationService * IJobService Puede elegir devolver un `ApiResponse` desde su endpoint. {% code collapsedlinecount="10" %} ```powershell return new ApiResponse { StatusCode = 404 }; ``` {% endcode %} Una vez que haya definido su fichero de endpoint de C#, puede añadirlo editando `endpoints.ps1`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#' ``` {% endcode %} 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) ### Consulte también * [Devolutions Academy – Añadir el restablecimiento de la contraseña de usuario](https://academy.devolutions.net/student/activity/3546111-part-6-adding-reset-user-password) * [Devolutions Academy – Estado del usuario/actualizar los detalles del usuario](https://academy.devolutions.net/student/activity/3546046-part-5-user-status-refresh-user-details) * [Devolutions Academy – Añadir la función de desbloqueo de usuario](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) * [Devolutions Academy – Crear un endpoint de variable](https://academy.devolutions.net/student/activity/3466016-creating-a-variable-endpoint) * [Devolutions Academy – Crear un endpoint de cadena de consulta](https://academy.devolutions.net/student/activity/3466018-creating-a-query-string-endpoint) --- # 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.