Saltar al contenido principal

Enviar consultas mediante REST API

Información general​

Teradata Query Service es una REST API para Vantage que puede utilizar para ejecutar declaraciones SQL estándar sin administrar controladores del lado del cliente. Utilice el servicio de consulta si desea consultar y acceder a la base de datos de análisis a través de una REST API.

Este tutorial proporciona ejemplos de casos de uso comunes para ayudarlo a comenzar con Query Service API.

Prerrequisitos​

Antes de comenzar, asegúrese de tener:

Nota

Si necesita una instancia de prueba de Vantage, puede obtener una de forma gratuita en https://clearscape.teradata.com

  • Nombre de host del servicio de consulta y nombre del sistema
  • Credenciales de autorización para conectarse a la base de datos

¿Tiene problemas con los requisitos previos? Póngase en contacto con Teradata para obtener información de configuración.

Ejemplos de API de servicio de consulta​

Al utilizar los ejemplos, tenga en cuenta que:

  • Los ejemplos de este documento utilizan Python y puede utilizarlos para crear ejemplos en el idioma que elija.
  • Los ejemplos proporcionados aquí están completos y listos para su uso, aunque la mayoría requiere un poco de personalización.
    • Los ejemplos de este documento utilizan la URL https://<QS_HOSTNAME>:1443/.
    • Reemplace las siguientes variables con su propio valor:
      • <QS_HOSTNAME>: Servidor donde está instalado Query Service
      • <SYSTEM_NAME>: Alias ​​preconfigurado del sistema
Nota

Si su instancia de Vantage se proporciona a través de ClearScape Analytics Experience,<QS_HOSTNAME>, es la URL del host de su entorno de ClearScape Analytics Experience, <SYSTEM_NAME> es "local".

Conectarse a su instancia de Query Service​

Proporcione credenciales válidas para acceder a la base de datos de Analytics de destino mediante la autenticación HTTP básica o JWT.

Autenticación básica HTTP​

El nombre de usuario y la contraseña de la base de datos se combinan en una cadena ("username : password") que posteriormente se codifica mediante Base64. La respuesta de la API contiene el método de autorización y las credenciales codificadas.

Solicitud

Respuesta

Autenticación JWT​

Prerequisites:

  • El usuario ya debe existir en la base de datos.
  • La base de datos debe estar habilitada para JWT.

Solicitud

Respuesta

Realice una solicitud API simple con opciones básicas​

En el siguiente ejemplo, la solicitud incluye:

  • SELECT * FROM DBC.DBCInfo: la consulta al sistema con el alias <SYSTEM_NAME>.

  • 'format': 'OBJECT': El formato de respuesta. Los formatos admitidos son: objeto JSON, matriz JSON y CSV.

    Nota

    El formato de objeto JSON crea un objeto JSON por fila donde el nombre de la columna es el nombre del campo y el valor de la columna es el valor del campo.

  • 'includeColumns': true: la solicitud para incluir metadatos de columna, como nombres y tipos de columnas, en la respuesta.

  • 'rowLimit': 4: el número de filas que se devolverán de una consulta.

Solicitud

Respuesta

Para conocer los parámetros de respuesta, consulte la Guía de instalación, configuración y uso de Query Service.

Solicitar una respuesta en formato CSV​

Para devolver una respuesta API en formato CSV, configure el campo *format* en la solicitud con el valor *CSV*.

El formato CSV contiene solo los resultados de la consulta y no los metadatos de respuesta. La respuesta contiene una línea para cada fila, donde cada línea contiene las columnas de la fila separadas por una coma. El siguiente ejemplo devuelve los datos como valores separados por comas.

Solicitud

Respuesta

Utilice una sesión explícita para enviar una consulta​

Utilice sesiones explícitas cuando una transacción necesite abarcar varias solicitudes o cuando utilice tablas volátiles. Estas sesiones solo se reutilizan si hace referencia a las sesiones en una solicitud de consulta. La solicitud se pone en cola si hace referencia a una sesión explícita que ya está en uso.

  1. Crear una sesión Envíe una solicitud POST al punto final /system/<SYSTEM_NAME>/sessions. La solicitud crea una nueva sesión de base de datos y devuelve los detalles de la sesión como respuesta.

    En el siguiente ejemplo, la solicitud incluye 'auto_commit': True: la solicitud para confirmar la consulta al finalizar.

    Solicitud

    Respuesta

  2. Utilice la sesión creada en el Paso 1 para enviar consultas.

    Envíe una solicitud POST al punto final /system/<SYSTEM_NAME>/queries.

    La solicitud envía consultas al sistema de destino y devuelve la versión y el número de versión del sistema de destino.

    En el siguiente ejemplo, la solicitud incluye:

    • SELECT * FROM DBC.DBCInfo: la consulta al sistema con el alias <SYSTEM_NAME>.
    • 'format': 'OBJECT': el formato de respuesta.
    • 'Session' : <Session ID>: el ID de sesión devuelto en el Paso 1 para crear una sesión explícita.

    Solicitud

    Respuesta

Utilizar consultas asincrónicas​

Utilice consultas asincrónicas cuando el rendimiento de un sistema o red se vea afectado por la consulta de un gran grupo de datos o consultas de larga duración.

  1. Envíe consultas asincrónicas al sistema de destino y recupere un ID de consulta Envíe una solicitud POST al punto final /system/<SYSTEM_NAME>/queries. En el siguiente ejemplo, la solicitud incluye: * SELECT * FROM DBC.DBCInfo: la consulta al sistema con el alias <SYSTEM_NAME>. * 'format': 'OBJECT': el formato de respuesta. * 'spooled_result_set': True: la indicación de que la solicitud es asincrónica.

    Solicitud

    Respuesta

  2. Obtenga los detalles de la consulta utilizando el ID recuperado en el Paso 1

    Envíe una solicitud GET al punto final /system/<SYSTEM_NAME>/queries/<queryID>, reemplazando <queryID> con el ID recuperado en el Paso 1.

    La solicitud devuelve los detalles de la consulta específica, incluidos queryState, queueOrder, queueDuration, etc. Para obtener una lista completa de los campos de respuesta y sus descripciones, consulte la Guía de instalación, configuración y uso de Query Service.

    Solicitud

    Respuesta

  3. Ver el conjunto de resultados de la consulta asincrónica

    Envíe una solicitud GET al punto final /system/<SYSTEM_NAME>/queries/<queryID>/results, reemplazando <queryID> con el ID recuperado en el Paso 1.

    La solicitud devuelve una matriz de los conjuntos de resultados y los recuentos de actualizaciones producidos por la consulta enviada.

    Solicitud

    Respuesta

Obtener una lista de consultas activas o en cola​

Envíe una solicitud GET al punto final /system/<SYSTEM_NAME>/queries. La solicitud devuelve los ID de las consultas activas.

Solicitud

Respuesta

Recursos​

Nota

Si tiene alguna pregunta o necesita más ayuda, visite nuestro foro de la comunidad donde podrá obtener ayuda e interactuar con otros miembros de la comunidad.

También de interés