Conexión a un flujo de datos y consumo de datos

Utilice los siguientes pasos para conectarse a un flujo de datos y consumir datos:

Paso 1: Crear la URL WebSocket

Lea los siguientes valores del YAML AsyncAPI generado:

servers.<name>.protocol: ws o wss.
servers.<name>.host: nombre de host y, cuando está presente, puerto.
channels.<name>.address: complete la ruta WebSocket para el flujo de datos.

wss://<server-host><channel-address>?begin=<percent-encoded-begin-value>

No codifique la ruta de acceso: OCI GoldenGate, un despliegue local y un proxy inverso pueden exponer diferentes prefijos de enrutamiento. Copie la dirección de canal y host del YAML generado o los enlaces canónicos devueltos por la API de REST.

Paso 2: Seleccione el valor inicial

Especifique el valor BEGIN según las directrices proporcionadas en la siguiente tabla:

Valor	Usar	Directrices
`now`	Empezar con nueva actividad	Se ha convertido al registro de hora actual y se ha resuelto en la pista disponible. Los cambios realizados antes del punto de resolución no se entregan.
`earliest`	Relleno inicial desde el rastro disponible	Convertido en registro de hora cero. La entrega comienza en el primer registro que aún está disponible en la pista configurada, no necesariamente en el inicio del historial de origen.
Registro de hora de ISO 8601	Comience cerca de un límite de tiempo de negocio	El servicio realiza una consulta basada en registro de hora. Utilice una zona horaria explícita, por ejemplo, `2026-07-13T04:00:00Z`.
Guardado `pos`	Recuperación después de una ejecución anterior correcta	El servicio realiza una consulta basada en posiciones. El resultado cuando la posición no está disponible depende de la calidad del servicio.

Porcentaje de codificación del valor inicial

Un token pos puede contener caracteres como +, / y = que tienen un significado especial en una URL. Porcentaje de codificación del token completo antes de agregarlo a la cadena de consulta. No modifique ni descodifique el token en la lógica de aplicación.

Paso 3: Autenticación y TLS

Seleccione el método de autenticación. Utilice la siguiente tabla para determinar el método más adecuado:

Modo	Cuándo se usa	Respuesta del cliente
Autenticación básica	Común con un servicio expuesto directamente o un proxy inverso	Envíe una cabecera `Authorization: Basic ...`. Mantenga las credenciales en un almacén secreto o en una inyección de entorno, no en la URL ni en el código fuente.
Autenticación del resumen	Cuando lo requiera el proxy inverso	Utilice un cliente o una plantilla generada que implante la comprobación de resumen HTTP durante el establecimiento de comunicación WebSocket.
Certificado de cliente	Autenticación de servicio basada en certificados o TLS mutua	Cargue el certificado de cliente y la clave privada en el contexto de TLS y valide el servidor con la CA configurada.
Proxy inverso seguro	El gateway termina o reenvía TLS	Siga el modo de autenticación de proxy. Un proxy seguro puede requerir credenciales básicas/de resumen y un certificado de cliente.

Paso 4: Generar un cliente desde AsyncAPI

Oracle proporciona una plantilla de cliente WebSocket para AsyncAPI Generator. Puede generar JavaScript, Python, Java, Go o todos los clientes soportados. El generador requiere Node.js 18.12 o posterior y npm 8.19 o posterior.

npm install -g @asyncapi/generator

git clone https://github.com/oracle-samples/websocket-client-template.git
cd websocket-client-template

ag /path/to/sales-orders.yaml .
  -o output
  -p server=production
  -p language=python
  -p authorization=basic

cd output
python -m pip install -r requirements.txt
export ASYNCAPI_WS_CLIENT_USERNAME="$OGG_USER"
export ASYNCAPI_WS_CLIENT_PASSWORD="$OGG_PASSWORD"
python client.py

La plantilla también soporta las variables de certificado ASYNCAPI_WS_CLIENT_CERT, ASYNCAPI_WS_CLIENT_KEY y ASYNCAPI_WS_CA_CERT. Revise las versiones de código y dependencia generadas en el proceso de desarrollo de software seguro habitual de su organización.

Paso 5: Describir los mensajes WebSocket

La carga útil de mensaje habitual es una matriz JSON. Un marco puede contener uno o más registros de esquema, metadatos, DML o DDL. El cliente debe iterar la matriz y clasificar cada objeto de forma independiente.

Backpressure: el servicio envía registros sin una confirmación de cliente por registro. Mantenga el bucle de recepción ligero. Ponga el procesamiento de negocio lento detrás de una cola interna limitada o una capa temporal duradera, controle la profundidad de la cola y detenga o escale al consumidor antes de que se agote la memoria.

Paso 6: Bucle de procesamiento de consumidor

Reciba un mensaje WebSocket completo.
Analizar la matriz de JSON. Cuando CloudEvents está activado, desenvuelva el ajuste del miembro data.
Clasificar registros de esquema, metadatos de flujo, metadatos de objeto, DML y DDL.
Valide los registros con el último esquema almacenado en caché cuando sea necesaria la validación.
Aplique la operación de negocio o publíquela en un sistema descendente duradero.
Una vez que la operación se haya realizado correctamente, guarde el registro pos con el diseño de punto de control atómico o idempotente seleccionado.
En caso de pérdida de conexión, vuelva a conectarse con el último pos duradero y el retroceso exponencial.