Usar la API de Datastream

Descripción general

Datastream proporciona una API de REST para administrar de manera programática tus opciones de configuración de conectividad privada, perfiles de conexión y transmisiones. La API de REST se define a través de recursos asociados con la creación y administración de configuraciones de conectividad privada, perfiles de conexión y transmisiones. Para obtener detalles sobre todos los recursos y sus métodos, consulta la Referencia de la API de Datastream.

Cuando envíes solicitudes directamente a la API de REST de Datastream, debes crear el formato correcto de la solicitud, autorizarla como usuario autenticado y procesar las respuestas que se muestren. Muchas de las tareas en esta documentación proporcionan ejemplos de API que usan cURL.

Para obtener más ejemplos del uso de las APIs, consulta la página de la solicitud en la Referencia de la API de Datastream. Cada página tiene ejemplos que llaman a la API en varios lenguajes de programación, así como un explorador específico de la solicitud para ayudarte a ver qué se incluye en una solicitud con formato correcto y qué esperar en la respuesta.

También usas la API de Datastream, de forma indirecta, cuando usas cualquiera de las siguientes formas de administración de instancias:

Google Cloud CLI: Una interfaz de línea de comandos (CLI) que puedes usar para trabajar con instancias.
Consola de Google Cloud: Es una interfaz web gráfica.

La ventaja de usar estos métodos, en especial la consola de Google Cloud, es que pueden simplificar en gran medida la administración de los parámetros de configuración de conectividad privada, los perfiles de conexión y las transmisiones (según tu caso de uso). Si recién comienzas a usar Datastream, te recomendamos que empieces con una de estas herramientas antes de trabajar directamente con la API de REST.

Habilite la API

Para usar la API de Datastream, debes habilitarla:

Consola

Habilita la API de Datastream.
Selecciona tu proyecto.
Selecciona Continuar.

gcloud

Ingresa lo siguiente para mostrar los ID de tus proyectos de Google Cloud:
```
gcloud projects list
```

Configura el proyecto predeterminado:

gcloud config set project YOUR_PROJECT_ID

Habilita la API de Datastream:

gcloud services enable datastream.googleapis.com

Permisos

Debes tener los permisos necesarios para usar la API de Datastream. Entre estos permisos, se incluyen los siguientes:

Administrador de Datastream: Con este permiso, un usuario obtiene acceso a todos los recursos de Datastream que se usan para administrar las configuraciones de conectividad privada, los perfiles de conexión y las transmisiones.
Visualizador de Datastream: Con este permiso, un usuario tiene acceso de solo lectura a los parámetros de configuración de conectividad privada, los perfiles de conexión y las transmisiones de Datastream.

Google Cloud ofrece Identity and Access Management (IAM), que te permite brindar acceso más detallado a recursos específicos de Google Cloud y evita el acceso no deseado a otros recursos. Puedes obtener y establecer permisos para Datastream mediante la Google Cloud Console, los métodos de IAM de la API o el SDK de Google Cloud. Para obtener más información, consulta Otorga, cambia y revoca el acceso a los recursos.

Ejemplos de API

Puedes ver ejemplos del uso de la API de Datastream con cURL en las siguientes páginas de la documentación de Datastream:

Proporciona datos JSON desde un archivo

Cuando usas la API con cURL, proporcionas valores de propiedad mediante la línea de comandos. Si trabajas con valores sensibles, como contraseñas o llaves de seguridad, proporcionarlos en la línea de comandos representa un riesgo de seguridad. Para mayor seguridad, puedes crear un archivo que contenga los datos JSON de la llamada a la API y proporcionar la ruta de acceso al archivo en la línea de comandos.

Para proporcionar datos JSON a tu llamada a la API cURL desde un archivo, haz lo siguiente:

Crea un archivo que contenga todo lo que esté entre comillas simples para el campo --data.

Incluye las llaves, pero no las comillas simples.

En la línea de comandos, proporciona la ruta de acceso al archivo, precedida por el carácter @, como el parámetro --data:

--data @<path-to-file>/<filename>

Por ejemplo, para crear un perfil de conexión para una fuente de MySQL, podrías crear un archivo llamado request.json con el siguiente contenido:

{
  "displayName": "my MySQL connection profile",
  "mysql": {
    "host": "10.11.12.13",
    "port": 3306,
    "username": "myusername",
    "password": "mypassword"
  }
}

Luego, usarías el siguiente comando cURL en la línea de comandos:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data @./request.json \
     -X POST \
     https://datastream.googleapis.com/v1/projects/myProject/locations/myLocation/connectionProfiles?connectionProfileId=myMySQLconnectionprofile

Cómo trabajar con llamadas a la API de larga duración

Algunas llamadas a la API, como la creación de objetos, pueden tardar un poco en completarse. Debido a que la API es asíncrona, la llamada se muestra de inmediato, incluso si la operación aún está en curso. Si una llamada a la API posterior usa el objeto recién creado, debes esperar a que se complete la primera operación antes de continuar.

Puedes usar la API de Datastream para administrar operaciones. Esto incluye lo siguiente:

Datastream y el Servicio de descubrimiento de API de Google

El Servicio de descubrimiento de API de Google es un servicio que puedes usar para descubrir las API de Google. Por ejemplo, cuando usas la herramienta Explorador de APIs de Google , estás usando Discovery Service.

En el servicio de descubrimiento, Datastream se representa como "datastream" (por ejemplo: https://datastream.googleapis.com/$discovery/rest?version=v1).