Cloud Storage

El conector de Google Cloud Storage te permite conectarte a Google Cloud Storage y realizar operaciones de transferencia de archivos.

Antes de comenzar

Antes de usar el conector de Cloud Storage, realiza las siguientes tareas:

  • En tu proyecto de Google Cloud, haz lo siguiente:
    • Otorga el rol de IAM roles/connectors.admin al usuario. configurar el conector.
    • Otorga los siguientes roles de IAM a la cuenta de servicio que deseas usar para el conector:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor
      • roles/storage.admin

      Una cuenta de servicio es un tipo de Cuenta de Google especial que representa a un usuario no humano que debe autenticarse y tener autorización para acceder a los datos de las APIs de Google. Si no tienes una cuenta de servicio, debes crear una. Para obtener más información, consulta Crea una cuenta de servicio.

    • Habilita los siguientes servicios:
      • secretmanager.googleapis.com (API de Secret Manager)
      • connectors.googleapis.com (API de conectores)

      Para comprender cómo habilitar servicios, consulta Habilita servicios.

    Si estos servicios o permisos no se habilitaron antes para tu proyecto, se te solicitará que los habilites cuando configures el conector.

Configura el conector

Para configurar el conector, debes crear una conexión a tu fuente de datos (sistema de backend). Una conexión es específica de una fuente de datos. Significa que, si tienes muchas fuentes de datos, debes crear una conexión independiente para cada fuente. Para crear una conexión, sigue estos pasos:

  1. En la consola de Cloud, ve a la página Conectores de Integration > Conexiones y, luego, selecciona o crea un proyecto de Google Cloud.

    Ir a la página Conexiones

  2. Haz clic en + CREAR NUEVO para abrir la página Crear conexión.
  3. En la sección Ubicación, elige la ubicación para la conexión.
    1. Región: selecciona una ubicación de la lista desplegable.

      Para obtener la lista de todas las regiones compatibles, consulta Ubicaciones.

    2. Haz clic en SIGUIENTE.
  4. En la sección Detalles de la conexión, completa lo siguiente:
    1. Conector: selecciona Cloud Storage en la lista desplegable de Conectores disponibles.
    2. Versión del conector: selecciona la versión del conector de la lista desplegable de versiones disponibles.
    3. En el campo Nombre de la conexión, ingresa un nombre para la instancia de conexión.

      Los nombres de las conexiones deben cumplir con los siguientes criterios:

      • Los nombres de las conexiones pueden usar letras, números o guiones.
      • Las letras deben estar en minúsculas.
      • Los nombres de las conexiones deben comenzar con una letra y terminar con una letra o un número.
      • Los nombres de las conexiones no pueden superar los 63 caracteres.
    4. De manera opcional, ingresa una Descripción para la instancia de conexión.
    5. Cuenta de servicio: Selecciona una cuenta de servicio que tenga los roles necesarios.
    6. De manera opcional, configura los parámetros de nodo de conexión:

      • Cantidad mínima de nodos: Ingresa la cantidad mínima de nodos de conexión.
      • Cantidad máxima de nodos: Ingresa la cantidad máxima de nodos de conexión.

      Un nodo es una unidad (o réplica) de una conexión que procesa transacciones. Se requieren más nodos para procesar más transacciones para una conexión y, del mismo modo, se requieren menos para procesar menos transacciones. Para comprender cómo los nodos afectan el precio del conector, consulta Precios de nodos de conexión. Si no ingresas ningún valor, se establecen de forma predeterminada los nodos mínimos en 2 (para una mejor disponibilidad) y los nodos máximos se establecen en 50.

    7. ID del proyecto: Ingresa el ID del proyecto de Google Cloud en el que residen los datos.
    8. De forma opcional, haz clic en + AGREGAR ETIQUETA para agregar una etiqueta a la conexión en forma de un par clave-valor.
    9. Haz clic en SIGUIENTE.
  5. Revisión: Revisa tu conexión.
  6. Haz clic en Crear.

Entidades, operaciones y acciones

Todos los Integration Connectors proporcionan una capa de abstracción para los objetos de la aplicación conectada. Solo puedes acceder a los objetos de una aplicación a través de esta abstracción. La abstracción se expone como entidades, operaciones y acciones.

  • Entidades: Una entidad puede considerarse como un objeto o una colección de propiedades en la aplicación o servicio conectados. La definición de una entidad difiere de conector a conector. Por ejemplo, en un conector de bases de datos, las tablas son las entidades; en un conector de servidor de archivos, las carpetas son las entidades; en un conector de sistema de mensajería, las colas son las entidades.

    Sin embargo, es posible que un conector no admita o tenga ninguna entidad, en cuyo caso la lista Entities estará vacía.

  • Operaciones: Una operación es la actividad que puedes realizar en una entidad. Puedes realizar cualquiera de las siguientes operaciones en una entidad:

    Cuando se selecciona una entidad de la lista disponible, se genera una lista de operaciones disponibles para esa entidad. Para obtener una descripción detallada de las operaciones, consulta las operaciones de entidades de la tarea de conectores. Sin embargo, si un conector no admite ninguna de las operaciones de entidad, tales operaciones operaciones no aparecen en la lista Operations.

  • Acción: Una acción es una función de primera clase que está disponible para la integración mediante la interfaz de Conectores. Una acción te permite realizar cambios en una entidad o entidades y variar de un conector a otro. Normalmente, una acción tendrá algunos parámetros de entrada y una parámetro. Sin embargo, es posible que un conector no admita ninguna acción, en cuyo caso la lista Actions estará vacía.

Limitaciones del sistema

El conector de Google Cloud Storage puede procesar un máximo de 10 transacciones por segundo por nodo y limita cualquier transacción que supere este límite. De forma predeterminada, Integration Connectors asigna 2 nodos (para una mejor disponibilidad) por una conexión.

Para obtener información sobre los límites aplicables a Integration Connectors, consulta Límites.

Acciones

La conexión de Google Cloud Storage admite las siguientes acciones:

Acción DownloadObject

En la siguiente tabla, se describen los parámetros de entrada de la acción DownloadObject.

Nombre del parámetro Obligatorio Tipo de dato Descripción
Propiedades Sí String Nombre del bucket en el que se encuentra el objeto que se descargará.
ObjectFilePath No String Nombre del objeto que se debe descargar. Si no se especifica, se descargarán todos los objetos del bucket especificado.

Si el objeto que deseas descargar está presente en una carpeta secundaria de un bucket, debes proporcionar la ruta completa de ese objeto. Por ejemplo, para descargar logfile.txt que está presente en el folderA de bucket_01, la ruta de acceso del objeto debe ser folderA/logfile.txt.

HasBytes No Booleano Indica si se debe descargar contenido como bytes. Los valores válidos son true o false. Si se configura como true, el contenido se descarga como una cadena codificada en Base64.

De forma predeterminada, el campo HasBytes se establece como false.
UpdatedEndDate No Fecha El período de finalización para descargar los objetos. Si no se especifica, los objetos se descargarán desde la UpdatedStartDate especificada hasta la fecha actual.
UpdatedStartDate No Fecha Inicio del período para descargar objetos. Si no se especifica, los objetos se descargarán desde el inicio del tiempo hasta la UpdatedEndDate.

Para ver ejemplos sobre cómo configurar la acción DownloadObject, consulta Ejemplos.

Acción UploadObject

En la siguiente tabla, se describen los parámetros de entrada de la acción UploadObject.

Nombre del parámetro Obligatorio Tipo de dato Descripción
Propiedades Sí String Nombre del bucket al que se subirá el objeto.
FolderPath No String La ruta de acceso a la carpeta en la que se debe subir el objeto.
ContentBytes No String Contenido para subir en forma de bytes (string codificada en base64).
HasBytes No Booleano Indica si se debe subir contenido como bytes. Valores válidos: true o false. Si se configura como true, el contenido que deseas subir debe ser una string codificada en Base64.

De forma predeterminada, el campo HasBytes se establece como false.
Contenido Sí String El contenido que se subirá.
ObjectName No String El nombre del objeto que se subirá.

Para ver ejemplos sobre cómo configurar la acción UploadObject, consulta Ejemplos.

Action CopyObject

En la siguiente tabla, se describen los parámetros de entrada de la acción CopyObject.

Nombre del parámetro Obligatorio Tipo de dato Descripción
BucketSource Sí String Nombre del bucket desde el cual deseas copiar el objeto.
ObjectSource Sí String Ruta completa de la carpeta en la que deseas copiar el objeto.
BucketDestination Sí String El nombre del bucket en el que deseas copiar el objeto.
ObjectDestination No String Ruta completa de acceso del destino, incluido el nombre del objeto. Si no especificas ningún nombre de objeto, se conserva el nombre del objeto de origen.

Para ver ejemplos sobre cómo configurar la acción CopyObject, consulta Ejemplos.

Action MoveObject

En la siguiente tabla, se describen los parámetros de entrada de la acción MoveObject.

Nombre del parámetro Obligatorio Tipo de dato Descripción
BucketSource Sí String Nombre del bucket desde el cual deseas mover el objeto.
ObjectSource Sí String Ruta de acceso completa de la carpeta a la que deseas mover el objeto.
BucketDestination Sí String El nombre del bucket al que deseas mover el objeto.
ObjectDestination No String Ruta completa de acceso del destino, incluido el nombre del objeto. Si no especificas ningún nombre de objeto, se conserva el nombre del objeto de origen.

Acción DeleteObject

En la siguiente tabla, se describen los parámetros de entrada de la acción DeleteObject.

Nombre del parámetro Obligatorio Tipo de dato Descripción
BucketSource Sí String Nombre del bucket en el que se encuentra el objeto que se borrará.
ObjectSource Sí String Nombre del objeto que deseas borrar.
Generación No Double Versión del objeto que se borrará. Si está presente, borra de forma permanente la revisión especificada del objeto, en lugar de la versión más reciente, que es el comportamiento predeterminado.
IfGenerationMatch No Double Hace que la operación de eliminación sea condicional si la generación actual del objeto coincide con el valor especificado. Establecer este valor en 0 hace que la operación sea exitosa solo si no hay versiones publicadas del objeto.
IfGenerationNotMatch No Double Hace que la operación de borrado sea condicional si la generación actual del objeto no coincide con el valor especificado. Si no existe un objeto publicado, la condición previa falla. Establecer este valor en 0 hace que la operación sea exitosa solo si hay una versión publicada del objeto.
IfMetagenerationMatch No Double Hace que la operación de eliminación sea condicional y se ejecute si la metageneración actual del objeto coincide con el valor especificado.
IfMetagenerationNotMatch No Double Hace que la operación de eliminación sea condicional y se ejecute si la metageneración actual del objeto no coincide con el valor especificado.

Acción SignURL

En la siguiente tabla, se describen los parámetros de entrada de la acción SignURL, que crea una URL firmada para el objeto especificado.

Nombre del parámetro Obligatorio Tipo de dato Descripción
Propiedades Sí Cadena El nombre del bucket en el que reside el objeto.
Objeto Sí Cadena El nombre del objeto para el que se generará la SignedURL.
RequestMethod No Cadena El método que usará la solicitud firmada. El valor predeterminado es GET.
Ubicación No Cadena Ubicación del bucket especificado. El valor predeterminado es auto.
ActiveDateTime No Cadena La fecha y hora en la que se activará la SignedURL. Si no se especifica, se usará la fecha y hora actual.
Consulta No Cadena La cadena de búsqueda que se debe incluir cuando se usa la SignedURL. Si no se especifica, no se usará ninguna string de consulta.
CustomHeaders No Cadena Una lista separada por comas de name=value de los encabezados que se usarán con la SignedURL. Si no se especifica, no se usarán encabezados personalizados.
ExpiresIn Sí Cadena La hora de vencimiento de la SignedURL. Debe tener el formato 1d2h3m4s y el valor máximo es 7d0h0m0s.
HmacAccessKey No Cadena La clave de acceso HMAC. Para obtener información, consulta Claves HMAC.
HmacSecret No Cadena El secreto HMAC.

Ejemplos

En los ejemplos de esta sección, se describen las siguientes operaciones:

  • Enumera todos los objetos
  • Enumera todos los objetos de un bucket
  • Enumera todos los depósitos
  • Descarga un objeto
  • Descarga un objeto binario
  • Sube un objeto binario a un bucket
  • Subirás un objeto a un bucket.
  • Sube un objeto a una carpeta
  • Copiar un objeto
  • Mover un objeto
  • Borrar un objeto
  • Crear una URL firmada para un objeto

En la siguiente tabla, se enumeran las situaciones de muestra y la configuración correspondiente en la tarea de conectores:

Tarea Configuración
Enumera todos los objetos
  1. En el cuadro de diálogo Configure connector task, haz clic en Entities.
  2. Selecciona la entidad Objects y, luego, la operación List.
  3. Haz clic en Listo.

Esto enumera todos los objetos en todos los depósitos. Los objetos se enumeran en el parámetro de respuesta connectorOutputPayload de la tarea Connectors.
Enumera todos los objetos de un bucket
  1. En el cuadro de diálogo Configure connector task, haz clic en Entities.
  2. Selecciona la entidad Objects y, luego, la operación List.
  3. Haz clic en Listo.
  4. Configura filterClause con el nombre del bucket del que deseas enumerar los objetos. Para configurar la cláusula, en la sección Task Input de la tarea Connectors, haz clic en filterClause y, luego, ingresa Bucket = 'BUCKET_NAME' en el campo Valor predeterminado. Por ejemplo, Bucket = 'bucket_01'.
Enumera todos los depósitos
  1. En el cuadro de diálogo Configure connector task, haz clic en Entities.
  2. Selecciona la entidad Buckets y, luego, la operación List.
  3. Haz clic en Listo.
Descarga un objeto
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción DownloadObject y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa un valor similar al siguiente en el Campo Default Value: 
    {
  "Bucket": "bucket-test-01",
  "ObjectFilePath": "logfile.txt"
}

    4. En este ejemplo, se descarga el archivo logfile.txt. El contenido del archivo descargado está disponible en formato JSON en el parámetro de respuesta connectorOutputPayload de la tarea Connectors.
Descarga un objeto binario

Los pasos para descargar un objeto binario son los mismos que se usan a fin de descargar un objeto normal, como se describió anteriormente. Además, debes especificar HasBytes como true en el campo connectorInputPayload. Esta acción descarga el objeto como una cadena codificada en base64. Valor de muestra para el campo connectorInputPayload:

{
"Bucket": "bucket-test-01",
"ObjectFilePath": "image01.png",
"HasBytes" : true
}

Si la descarga se realiza de forma correcta, el resultado en el campo connectorOutputPayload será similar al siguiente:

{
"Success": "true",
"ContentBytes": "SGVsbG8gdGVzdCE\u003d"
}
Sube un objeto binario a un bucket
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción UploadObject y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa lo siguiente en el Campo Default Value: 
    {
"ContentBytes": "SGVsbG8gVGVzdCE=",
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01",
"HasBytes": true
}

    4. En este ejemplo, se crea el archivo test-file-01 en el bucket bucket-test-01. Si hay un archivo existente con el nombre test-file-01, se reemplazará.
Subirás un objeto a un bucket.
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción UploadObject y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa lo siguiente en el Campo Default Value: 
    {
"Content": "Hello test!",
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01.txt"
}

    4. En este ejemplo, se crea el archivo test-file-01.txt con el contenido Hello test! en el bucket bucket-test-01. Si hay un archivo existente con el nombre test-file-01.txt, se reemplazará.
Sube un objeto a una carpeta
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción UploadObject y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa lo siguiente en el Campo Default Value: 
    {
"Content": "Hello test!",
"Bucket": "bucket-test-01",
"FolderPath": "folderA",
"ObjectName": "test-file-01.txt"
}

    4. En este ejemplo, se crea el archivo test-file-01.txt con el contenido Hello test! en la carpeta folderA de bucket-test-01. Si la carpeta tiene un archivo existente con el nombre test-file-01.txt, se reemplazará.
Copiar un objeto
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción CopyObject y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa lo siguiente en el Campo Default Value: 
    {
"BucketSource": "bucket_01",
"ObjectSource": "folderA/logfile.txt",
"BucketDestination": "bucket_02",
"ObjectDestination": "folderB/logfile.txt"
}

    4. En este ejemplo, se copia el archivo folderA/logfile.txt de bucket_01 a folderB/logfile.txt en bucket_02.

Si la copia se realiza de forma correcta, el resultado en el campo connectorOutputPayload será similar al siguiente:

{
"Success": "true"
}
Mover un objeto
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción MoveObject y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa lo siguiente en el Campo Default Value: 
    {
"BucketSource": "bucket_01",
"ObjectSource": "folderA/logfile.txt",
"BucketDestination": "bucket_02",
"ObjectDestination": "folderB/logfile.txt"
}

    4. En este ejemplo, se mueve el archivo folderA/logfile.txt de bucket_01 a folderB/logfile.txt en bucket_02.

Si la copia se realiza de forma correcta, el resultado en el campo connectorOutputPayload será similar al siguiente:

{
"Success": "true"
}
Borrar un objeto
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción DeleteObject y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa lo siguiente en el Campo Default Value: 
    {
"BucketSource": "bucket_01",
"ObjectSource": "logfile.txt"
}

    4. En este ejemplo, se borra el archivo logfile.txt de bucket_01.

Si la copia se realiza de forma correcta, el resultado en el campo connectorOutputPayload será similar al siguiente:

{
"Success": "true"
}
Crear una URL firmada para un objeto
  1. En el cuadro de diálogo Configure connector task, haz clic en Actions.
  2. Selecciona la acción SignURL y haz clic en Listo.
  3. En la sección Task Input de la tarea Connectors, haz clic en connectorInputPayload y, luego, ingresa lo siguiente en el Campo Default Value: 
    {
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01.txt"
}

    4. En este ejemplo, se crea una URL firmada para el archivo test-file-01.txt, que se encuentra en el bucket bucket-test-01. Si la acción se realiza con éxito, obtendrás la URL firmada en la respuesta similar a la siguiente:

    {
"Success": "true",
"SignURL": "https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=
GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount
.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T18
1309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f16
9edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa849
6def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dc
c1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c2058
0e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a
66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823
a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b13344703
2ea7abedc098d2eb14a7"
}

Consideraciones

  • Un objeto descargable puede tener un tamaño máximo de 10 MB.
  • No puedes subir varios archivos con la acción UploadObject. Solo puedes subir un archivo.

Usar Terraform para crear conexiones

Puedes usar Terraform resource para crear una conexión nueva.

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.

Si quieres ver una plantilla de Terraform de muestra para crear conexiones, consulta la plantilla de muestra.

Cuando creas esta conexión con Terraform, debes configurar las siguientes variables en tu archivo de configuración de Terraform:

Nombre del parámetro Tipo de datos Obligatorio Descripción
project_id STRING Verdadero Es el ID del proyecto de Google Cloud en el que residen los datos.

Usa la conexión de Cloud Storage en una integración

Después de que crees la conexión, estará disponible en Apigee Integration y Application Integration. Puedes usar la conexión en una integración a través de la tarea Conectores.

  • Para comprender cómo crear y usar la tarea Conectores en la integración de Apigee, consulta Tarea Conectores.
  • Para comprender cómo crear y usar la tarea Conectores en Application Integration, consulta la Tarea Conectores.

Obtén ayuda de la Comunidad de Google Cloud

Puedes publicar tus preguntas y debatir sobre este conector en la comunidad de Google Cloud en Cloud Forums.

¿Qué sigue?