¿Está buscando integrar ServiceNow en su flujo de trabajo utilizando su API? Este tutorial lo guiará a través del proceso de configurar una cuenta de desarrollador de ServiceNow, crear una aplicación OAuth y realizar su primera llamada API usando PowerShell.

Paso 1: cree una cuenta de desarrollador de ServiceNow

1. Ve a la Portal para desarrolladores de ServiceNow y regístrese para obtener una cuenta.
2. Una vez que haya iniciado sesión, solicite una instancia de desarrollador personal siguiendo las instrucciones aquí.

Paso 2: acceda a su instancia de desarrollador

1. En el portal para desarrolladores, haga clic en su perfil y luego en “Administrar contraseña de instancia”.

   

2. Anote el nombre de su instancia, nombre de usuario y contraseña.
3. Inicie sesión en su instancia usando el formato de URL: https://[your-instance-name].service-now.com/login.do

   💡 Consejo: asegúrese de incluir login.do al final de la URL para evitar ver una página en blanco.

Paso 3: cree una aplicación OAuth

1. En su instancia de ServiceNow, navegue hasta Sistema OAuth > Registro de aplicaciones.

   

2. Haga clic en “Nuevo” y seleccione “Crear un punto final API de OAuth para clientes externos”.

   

   

3. Proporcione un nombre a la aplicación OAuth y guárdela. La aplicación creará un ID de cliente y un secreto de cliente con el que deberá autenticarse en la API.

   

Paso 4: cree una cuenta de usuario

1. Navegue a Administración de usuarios > Usuarios.

   

2. Cree una nueva cuenta de usuario que utilizará para acceder a la API.

   

   Selecciona el ID de usuario como mínimo y asegúrese de verificar Sólo acceso al servicio web. Esta opción restringirá a este usuario solo a la API.

   

3. Establecer una contraseña de usuario.

   Una vez que haya guardado la cuenta de usuario, abra la cuenta de usuario y haga clic en Configurar la clave.

   

Una vez que haya creado la aplicación OAuth y la cuenta de usuario, debería tener los siguientes valores:

• Nombre de instancia
• Nombre de usuario
• Contraseña de usuario
• Identificación del cliente
• Secreto del cliente

Necesitará estos valores para usarlos en su secuencia de comandos de PowerShell.

Paso 5: obtenga un token de acceso OAuth

En este punto, ahora debería tener una instancia de ServiceNow en funcionamiento para realizar la prueba. Ahora es el momento de consultar la API. Pero primero, debes obtener un token de acceso de OAuth. El token de acceso es lo que utilizará para autenticar todas las solicitudes API futuras.

Abra Visual Studio Code o cualquier IDE con el que esté trabajando y primero defina las variables para cada atributo que necesitará recopilado anteriormente.

$serviceNowInstance = 'your-instance-name'
$apiUrl = "https://$ServiceNowInstance.service-now.com/oauth_token.do"

Aquí, estamos configurando dos variables importantes:

• $serviceNowInstance: Esto debe reemplazarse con el nombre real de su instancia de ServiceNow.
• $apiUrl: Esto construye la URL completa para el punto final del token de OAuth. Estamos usando interpolación de cadenas para incluir el nombre de la instancia en la URL.

$oauthclientId = 'your-client-id'
$OAuthClientSecret = 'your-client-secret'
$Username = 'your-username'
$UserPassword = 'your-password'

En esta sección, estamos definiendo nuestras credenciales de OAuth:

• $oauthclientId y $OAuthClientSecret: Estos deben reemplazarse con el ID de cliente y el secreto de cliente que obtuvo al crear su aplicación OAuth en ServiceNow.
• $Username: este es el nombre de usuario de la cuenta de ServiceNow que está utilizando para acceder a la API.
• $UserPassword: La contraseña de usuario definida al crear el usuario.

$params = @{
    Uri                = $apiUrl
    SkipHttpErrorCheck = $true
    Method             = 'POST'
    StatusCodeVariable = 'StatusCode'
    Body               = @{
        grant_type    = "password"
        client_id     = $OAuthClientId
        client_secret = $OAuthClientSecret
        username      = $Username
        password      = (New-Object PSCredential "user", $UserPassword).GetNetworkCredential().Password
    }
}

Aquí, estamos creando una tabla hash. $params que se utilizarán como argumentos para nuestra llamada API:

• Uri: Esto está configurado en nuestro $apiUrlespecificando dónde enviamos la solicitud.
• SkipHttpErrorCheck: Ajustado a $true, esto le indica a PowerShell que no genere automáticamente un error si obtenemos un código de estado que no sea 200. Nos encargaremos de los errores nosotros mismos.
• Method: Estamos usando ‘POST’ porque enviamos datos al servidor para obtener nuestro token.
• StatusCodeVariable: Esto almacenará el código de estado HTTP en una variable llamada ‘StatusCode’, que usaremos más adelante para verificar si la solicitud fue exitosa.
• Body: Esta tabla hash anidada contiene los datos que enviamos al servidor:
  • grant_type: Estamos utilizando “contraseña” como nuestro tipo de concesión.
  • client_id y client_secret: Estas son nuestras credenciales de aplicación OAuth.
  • username: El nombre de usuario de ServiceNow.
  • password: Estamos extrayendo la contraseña de nuestro SecureString. Este código de apariencia compleja crea un objeto PSCredential temporal y luego extrae la contraseña como texto sin formato.

$response = Invoke-RestMethod @params

Esta línea es donde realmente hacemos la llamada API:

• Invoke-RestMethod es un cmdlet de PowerShell que envía solicitudes HTTP y HTTPS a servicios web y devuelve datos estructurados.
• Mediante el uso @paramsestamos salpicando nuestros parámetros, esencialmente pasando todos los pares clave-valor en nuestro $params tabla hash como parámetros individuales para Invoke-RestMethod.
• Esta llamada enviará una solicitud POST al punto final OAuth de nuestra instancia de ServiceNow, incluidas nuestras credenciales en el cuerpo de la solicitud.
• La respuesta del servidor (que debería incluir nuestro token de acceso si tiene éxito) se almacena en el $response variable.

if ($StatusCode -ne 200) {
    throw "Failed to generate access token. Error: $($response.error_description)"
}

Después de la solicitud, verificamos el código de estado:

• El código de estado HTTP 200 indica una solicitud exitosa.
• Si el código de estado no es 200, arrojamos un error, incluida la descripción del error de la respuesta.
• Esto nos ayuda a identificar rápidamente si algo salió mal con nuestra solicitud.

Finalmente, generamos la respuesta. Si tiene éxito, debería contener nuestro token de acceso junto con otros detalles como el tipo de token y el tiempo de vencimiento.

Paso 6: realice su primera llamada API

Ahora analicemos el código para realizar una llamada API:

$serviceNowInstance = 'your-instance-name'
$endpoint = 'table/incident'
$uri = "<https://$ServiceNowInstance.service-now.com/api/now/$Endpoint>"

$headers = @{
    'Authorization' = "Bearer $($response.access_token)"
}

$result = Invoke-RestMethod -Uri $uri -Headers $headers -Method Get
$result.result | Format-Table

Esto es lo que está pasando:

1. Configuramos la URL de nuestro punto final API.
2. Creamos un $headers tabla hash con nuestro token de autorización. El prefijo “Portador” forma parte de la especificación OAuth 2.0.
3. Usamos Invoke-RestMethod De nuevo, pero esta vez con diferentes parámetros:
   • Uri: La URL a la que enviamos la solicitud.
   • Headers: Nuestro encabezado de autorización.
   • Method: Estamos usando ‘Obtener’ para recuperar datos.
4. La respuesta de la API se almacena en $result.
5. Luego canalizamos $result.result a Format-Table para mostrar los datos en un formato de tabla ordenado.

Este Invoke-RestMethod La llamada es más simple que la anterior porque no enviamos un cuerpo con nuestra solicitud, solo recuperamos datos.

Bonificación: uso de tokens de actualización

Cuando su token de acceso caduque, puede usar un token de actualización para obtener uno nuevo sin necesidad de que el usuario inicie sesión nuevamente:

$params = @{
    Uri                = $apiUrl
    SkipHttpErrorCheck = $true
    Method             = 'POST'
    StatusCodeVariable = 'StatusCode'
    Body               = @{
        grant_type    = "refresh_token"
        refresh_token = $response.refresh_token
    }
}

$newTokenResponse = Invoke-RestMethod @params
if ($StatusCode -ne 200) {
    throw "Failed to refresh access token. Error: $($newTokenResponse.error_description)"
}

$newTokenResponse

Conclusión

Ahora configuró una cuenta de desarrollador de ServiceNow, creó una aplicación OAuth y realizó su primera llamada API. Esto es solo el comienzo de lo que puede hacer con la API ServiceNow. Experimente con diferentes puntos finales y comience a integrar ServiceNow en sus flujos de trabajo.

Para obtener información más detallada, consulte el documentación oficial de la API de ServiceNow.

¡Feliz codificación!