Usa vinculaciones de carga útil y expansiones de parámetros de Bash en sustituciones

En esta página, se explica cómo usar vinculaciones de carga útil y aplicar extensiones de parámetros de Bash para reemplazar variables asociadas con el activador de compilación. Si no estás familiarizado con el uso de variables de sustitución en la configuración de compilación, consulta Sustituye valores de variables.

Cloud Build te permite almacenar partes de la carga útil de eventos del activador como una variable de sustitución. Una carga útil de evento es el cuerpo del evento que invoca un activador. Las variables asociadas con una carga útil se conocen como vinculaciones y están disponibles para compilaciones invocadas por eventos de envío y extracción. Las vinculaciones te permiten acceder a los datos adicionales relacionados con tu compilación, como el lenguaje asociado con tu código fuente y el autor de una solicitud de extracción.

Cloud Build también permite a los usuarios aplicar ampliaciones de parámetros de bash a valores de variables de sustitución. Las expansiones de parámetros de bash te permiten manipular strings asociadas con variables existentes. Para manipular las strings, puedes escribir mayúsculas o reemplazar una substring.

Puedes usar vinculaciones de carga útil y aplicar expansiones de parámetros de Bash cuando defines o actualizas un activador de compilación en la consola de Google Cloud y en un archivo de configuración de Cloud Build. Además, puedes aplicar las expansiones de parámetros de bash cuando ejecutas compilaciones manuales.

Vinculaciones de carga útil

Puedes almacenar partes de la carga útil de del evento de tu activador como un valor de variable de sustitución. Las vinculaciones de carga útil están disponibles como valores variables para compilaciones invocadas por eventos de envío y extracción, y se pueden usar a fin de acceder a la carga útil de JSON cuando tu código fuente está en repositorios de GitHub o Cloud Source Repositories. Para obtener más información sobre las cargas útiles de eventos de GitHub, consulta Webhook event payloads (Cargas útiles de eventos de webhook). Si deseas obtener más información sobre las cargas útiles de eventos para Cloud Source Repositories, consulta Notificaciones para Cloud Source Repositories.

Puedes acceder a la información desde una carga útil de un evento con un prefijo designado, que representa la raíz de la carga útil del evento. A partir del prefijo, puedes usar la JSONPath syntax (sintaxis JSONPath) para acceder a la carga útil y extraer datos de ella. Los siguientes prefijos de carga útil están disponibles según tu tipo de evento:

Prefijo	Origen	Descripción
`push`	GitHub	Te permite acceder a campos dentro de tu carga útil de JSON para eventos de envío.
`pull_request`	GitHub	Te permite acceder a campos dentro de tu carga útil de JSON para eventos de solicitud de extracción.
`issue_comment`	GitHub	Te permite acceder a los campos de la carga útil JSON de los eventos de comentarios de problemas asociados con una solicitud de extracción.
`csr`	Cloud Source Repositories	Te permite acceder a campos dentro de tu carga útil de JSON para eventos de envío.

En el caso de los eventos asociados con la app de GitHub, también están disponibles los valores de las variables integradas is_collaborator y perm_level. El estado del usuario se verifica para los eventos de envío y extracción mediante los valores de variables push.pusher.name, pull_request.pull_request.user.login y issue_comment.comment.user.login. En la siguiente tabla, se muestra cómo incluir estos valores como valores variables del activador cuando tu código fuente está en GitHub:

Nombre de la variable	Valor de la variable	Descripción de la variable
`_PERM_LEVEL`	`$(perm_level)`	Obtiene el nivel de permiso del usuario.
`_IS_COLLABORATOR`	`$(is_collaborator)`	Se muestra `true` si el usuario es un colaborador.

Puedes usar los valores de las variables is_collaborator y perm_level para los eventos de envío, los eventos de solicitud de extracción y los eventos de solicitud de extracción controlados mediante un comentario. No es necesario preceder estos valores de variable con un prefijo.

Crea sustituciones mediante vinculaciones de carga útil

Para crear una variable de sustitución que usa una vinculación de carga útil, sigue estos pasos:

Abrir la página Activadores.
Si no creaste un activador de compilación, haz clic en Crear activador. De lo contrario, selecciona un activador existente.
En Variables de sustitución, haz clic en Agregar variable.
Agrega un nombre para tu Variable según la convención descrita a continuación:
- Las sustituciones deben comenzar con guion bajo (_) y usar solo letras mayúsculas y números (acorde a la expresión regular [A-Z0-9_]+). Esto evita los conflictos con las sustituciones integradas.
- La cantidad de parámetros está limitada a 100. La longitud de la clave de parámetro se limita a 100 bytes y la longitud del valor de parámetro se limita a 4,000 bytes.
Para obtener más información sobre cómo definir y usar sustituciones definidas por el usuario, consulta Usa sustituciones definidas por el usuario.

Agrega un valor en tu variable mediante un prefijo admitido.

Si tu código fuente está en GitHub, puedes consultar la información de la carga útil de tu evento dentro de las variables de sustitución mediante vinculaciones de carga útil. Para acceder a la carga útil de JSON de un evento push, usa el prefijo push o body. En el siguiente ejemplo, se usa el prefijo push en el valor de la variable como punto de entrada para acceder a la información de la carga útil JSON de tu compilación:

Nombre de la variable	Valor de la variable	Descripción de la variable
`_PUSH_NAME`	`$(push.repository.name)`	Obtiene el nombre del repositorio asociado con el evento de envío.
`_COMMITS`	`$(push.commits)`	Obtiene el arreglo de objetos de confirmación que describen cada confirmación enviada.
`_OWNER`	`$(push.repository.owner.name)`	Obtiene el nombre del propietario del repositorio.
`_URL`	`$(push.repository.html_url)`	Obtiene la URL de tu repositorio de GitHub.
`_LANGUAGE`	`$(push.repository.language)`	Obtiene el lenguaje de tu código fuente incluido en el mensaje.

Para obtener una lista de campos a los que puedes acceder con el prefijo push, consulta PushEvent.

Para acceder a la carga útil JSON de un evento de solicitud de extracción, usa el prefijo pull_request o body. En el siguiente ejemplo, el prefijo pull_request en el valor de la variable se usa como un punto de entrada para acceder a la información de la carga útil JSON de tu compilación:

Nombre de la variable	Valor de la variable	Descripción de la variable
`_PULL_REQUEST_ID`	`$(pull_request.pull_request.id)`	Obtiene el ID de la solicitud de extracción.
`_PULL_REQUEST_TITLE`	`$(pull_request.pull_request.title)`	Obtiene el título de la solicitud de extracción.
`_PULL_REQUEST_BODY`	`$(pull_request.pull_request.body)`	Obtiene el cuerpo de la solicitud de extracción.
`_USERNAME`	`$(pull_request.pull_request.user.login)`	Obtiene el nombre de usuario del remitente de la solicitud de extracción.
`_MERGE_TIME`	`$(pull_request.pull_request.merged_at)`	Obtiene la hora a la que se fusionó la solicitud de extracción.

Para obtener una lista de campos a los que puedes acceder con el prefijo pull_request, consulta PullRequestEvent.

Para acceder a la carga útil de JSON de un evento de confirmación, usa el prefijo commit. En el siguiente ejemplo, el prefijo commit en el valor de la variable se usa como punto de entrada para acceder a la información de la carga útil de JSON de tu compilación.

Nombre de la variable	Valor de la variable	Descripción de la variable
`_COMMIT_URL`	`$(commit.url)`	Obtiene la URL asociada con la confirmación.
`_COMMIT_USER`	`$(commit.author.login)`	Obtiene el nombre de usuario del autor de la confirmación
`_COMMIT_MESSAGE`	`$(commit.commit.message)`	Obtiene el mensaje de confirmación asociado con la confirmación
`_COMMIT_DATE`	`$(commit.commit.committer.date)`	Obtiene la fecha asociada con la confirmación
`_COMMIT_ADDITIONS`	`$(commit.files['*'].additions)`	Obtiene la cantidad de adiciones asociadas con archivos en la confirmación

Para obtener una lista de campos a los que puedes acceder con el prefijo commit, consulta Obtén una confirmación.

Si habilitas el Control de comentarios para un activador que invocad una solicitud de extracción, el evento que invoca al activador es un IssueCommentEvent y el prefijo asociado, issue_comment a fin de crear el adjunto de VLAN de supervisión. En los siguientes ejemplos, el prefijo issue_comment en el valor de la variable se usa como punto de entrada para acceder a la información de la carga útil JSON de tu compilación:

Nombre de la variable	Valor de la variable	Descripción de la variable
`_PULL_REQUEST_ID`	`$(issue_comment.issue.id)`	Obtiene el ID de la solicitud de extracción.
`_PULL_REQUEST_TITLE`	`$(issue_comment.issue.title)`	Obtiene el título de la solicitud de extracción.
`_STATE`	`$(issue_comment.state)`	Obtiene el estado de la solicitud de extracción (es decir, abierta, cerrada, etcétera).
`_LABELS`	`$(issue_comment.issue.labels)`	Obtiene la lista de etiquetas asociadas con la solicitud de extracción.
`_LABELS_URL`	`$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)`	Obtiene la URL asociada a la etiqueta que coincide con la descripción.

Para obtener una lista de campos a los que puedes acceder con el prefijo issue_comment, consulta IssueCommentEvent.

Si tu código fuente está en Cloud Source Repositories, puedes consultar la información de la carga útil de tu evento dentro de variables de sustitución con vinculaciones de carga útil. Para acceder a la carga útil de JSON desde un evento push, usa el prefijo csr o body. En el siguiente ejemplo, se usa el prefijo csr en el valor de la variable como punto de entrada para acceder a la información de la carga útil JSON de tu compilación.

Nombre de la variable	Valor de la variable	Descripción de la variable
`_REPO_NAME`	`$(csr.name)`	Obtiene el nombre del repositorio
`_REPO_URL`	`$(csr.url)`	Obtiene la URL del repositorio.
`_CREATED_REPO`	`$(csr.createRepoEvent)`	Indica si un usuario creó un repositorio
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	El nombre de la referencia (p. ej., “refs/heads/primary-branch”)

Para ver los campos adicionales a los que puedes acceder en Cloud Source Repositories, consulta Datos de notificación.

Expande los parámetros de Bash

Puedes aplicar ampliaciones de parámetros de Bash a variables predeterminadas y variables definidas por el usuario. Entre los ejemplos de operaciones admitidas se incluyen el reemplazo de substrings, la porción de string y el uso de mayúsculas. Por ejemplo, es posible que desees reemplazar una substring en una variable predeterminada y agregarla como etiqueta de imagen.

Las expansiones de parámetros de Bash que puedes especificar para las variables de sustitución son las siguientes:

Expansión de Bash	Descripción
`${var}`	Expande el valor de la string almacenada en `var`
`${var^}`	Cambia a mayúscula el primer carácter de la string
`${var^^}`	Usa mayúsculas todos los caracteres de la string
`${var,}`	Usa minúscula el primer carácter en la string
`${var,,}`	Usa minúsculas en todos los caracteres de la string
`${var:position}`	Quita los primeros `position` caracteres de la string
`${var:position:length}`	Porciona la string que comienza en el valor numérico especificado en `position` y también incluye el valor numérico especificado en `length`
`${var/substring/replacement}`	Reemplaza la instancia más a la izquierda del valor especificado en `substring` por el valor especificado en `replacement`.
`${var//substring/replacement}`	Reemplaza todas las instancias del valor especificado en `substring` por el valor especificado en `replacement`.
`${var/#substring/replacement}`	Reemplaza la primera instancia del valor especificado en `substring` con el valor especificado en `replacement` solo si `substring` es un prefijo de `var`.
`${var/%substring/replacement}`	Reemplaza la última instancia del valor especificado en `substring` con el valor especificado en `replacement` solo si `substring` es un sufijo de `var`.
`${#var}`	Recupera la longitud de la string
`${var:-default}`	Evalúa `var` como `default`, a menos que `var` ya esté definido.

También puedes especificar patrones que coincidan con la siguiente expansión de parámetros de Bash:

Expansión de Bash	Descripción
`${var#pattern}`	Quita los caracteres del lado izquierdo de una string hasta la instancia más a la izquierda de `pattern` especificada incluida.
`${var##pattern}`	Quita los caracteres del lado izquierdo de una string hasta la instancia más a la derecha del `pattern` especificado incluida.
`${var%pattern}`	Quita caracteres del lado derecho de una string hasta la primera instancia del `pattern` especificado incluida.
`${var%%pattern}`	Quita los caracteres del lado derecho de una string hasta la instancia del extremo izquierdo del `pattern` especificado incluida

Algunos de los patrones que puedes especificar son los siguientes:

Patrón	Descripción
`*`	Coincide con cero o más caracteres alfanuméricos
`?`	Coincide con cualquier carácter alfanumérico único
`[ccc]`	Coincide con cualquier carácter único en `ccc`, incluidos los rangos entre `a-z` o `0-9`
`[^c]`	Coincide con cualquier carácter alfanumérico no en `c`, incluido un rango de caracteres donde `lo` <= `c` <= `hi`
`c`	Coincide con cualquier carácter alfanumérico `c`
`\c`	Coincide con cualquier carácter `c`, incluidos caracteres que no sean alfanuméricos, como `*`, `?` o `\`

Aplica expansiones de parámetros de Bash

Para aplicar una expansión de parámetros de Bash a una variable de sustitución integrada o definida por el usuario:

Abrir la página Activadores.
Si no creaste un activador de compilación, haz clic en Crear activador. De lo contrario, selecciona un activador existente.
En Variables de sustitución, haz clic en Agregar variable.
Agrega un nombre para tu Variable según la convención descrita a continuación:
- Las sustituciones deben comenzar con guion bajo (_) y usar solo letras mayúsculas y números (acorde a la expresión regular [A-Z0-9_]+). Esto evita los conflictos con las sustituciones integradas.
- La cantidad de parámetros está limitada a 100. La longitud de la clave de parámetro se limita a 100 bytes y la longitud del valor de parámetro se limita a 4,000 bytes.
Para obtener más información sobre cómo definir y usar sustituciones definidas por el usuario, consulta Usa sustituciones definidas por el usuario.

Agrega un valor para la variable mediante la aplicación de una expansión de parámetros de Bash compatibles en una variable de sustitución integrada o en otra variable de sustitución definida por el usuario.

En el siguiente ejemplo, la variable de sustitución integrada $BRANCH_NAME tiene un valor predeterminado para Feature_Secret_Project_#v2. En la siguiente tabla, se muestran ejemplos de expansiones de parámetros de Bash que puedes aplicar a $BRANCH_NAME:

Nombre de la variable	Expansión de Bash	Valor de la variable	Descripción
`_BRANCH_LOWERCASE`	`${$BRANCH_NAME,,}`	`feature_secret_project_#v2`	Escribe en minúscula todos los caracteres de la cadena.
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#v2}`	`feature_secret_project`	Borra todos los caracteres del lado derecho de la string que coinciden con el patrón especificado
`_BRANCH_NO_PREFIX`	`${_BRANCH_NO_SUFFIX#*_}`	`secret_project`	Borra todos los caracteres hasta el primer guion bajo
`_BRANCH_FOR_IMAGE_NAME`	`${_BRANCH_NO_PREFIX//_/-}`	`secret-project`	Reemplaza todos los guiones bajos por guiones
`_IMAGE_NAME`	`my-app-${_BRANCH_FOR_IMAGE_NAME}-prod`	`my-app-secret-project-prod`	Construye el nombre de la imagen mediante la variable `_BRANCH_FOR_IMAGE_NAME` definida con anterioridad

Supongamos que _IMAGE_NAME está definido en tu activador como el valor especificado en la tabla anterior, my-app-secret-project-prod. Este valor anulará cualquier definición de _IMAGE_NAME en tu archivo de configuración de compilación. En el siguiente ejemplo, el valor de variable especificado para _IMAGE_NAME (my-app-secret-project-prod) reemplaza el valor predeterminado de _IMAGE_NAME (test-image) cuando se invoca el activador de compilación. a fin de crear el adjunto de VLAN de supervisión.

YAML

 steps:
 - name: 'gcr.io/cloud-builders/docker'
   args: ['build',
          '-t',
          'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
          '.']
 substitutions:
     _IMAGE_NAME: test-image #default value
 images: [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
 ]
 options:
     dynamicSubstitutions: true

JSON

 {
   'steps': [
     {
       'name': 'gcr.io/cloud-builders/docker',
       'args': [
         'build',
         '-t',
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
         '.'
       ]
     }
   ],
   'substitutions': {
     '_IMAGE_NAME': 'test-image' #default value
   },
   'images': [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
   ],
   "options": {
     "dynamic_substitutions": true
   }
 }

El campo dynamicSubstitutions, configurado en true en el ejemplo anterior, permite interpretar las expansiones de los parámetros de Bash. Si tu compilación invoca una compilación, el campo dynamicSubstitutions siempre se establece en true y no es necesario especificar en tu archivo de configuración de compilación. Si tu compilación se invoca de forma manual, debes configurar el campo dynamicSubstitutions como true para que las expansiones de los parámetros de bash se interpreten cuando se ejecuta tu compilación.

Usa expansiones de parámetros Bash con vinculaciones de carga útil

Puedes aplicar ampliaciones de parámetros de Bash a variables asociadas con vinculaciones de carga útil. Para ello, crea una variable nueva que haga referencia a la variable que contiene tus vinculaciones o vincúlalas con expansión de parámetros de Bash. En la siguiente tabla, se enumeran ejemplos de cómo puedes usar la expansión de parámetros de Bash con vinculaciones de carga útil:

Nombre de la variable	Valor de la variable	Descripción de la variable
`_URL`	`$(push.repository.html_url)`	Obtiene la URL del repositorio.
`_URL_CAPITAL`	`${_URL^^}`	Usa una expansión de parámetros de Bash para usar mayúsculas en todos los caracteres de la URL
`_APP_NAME`	`my-app-${_URL_CAPITAL}`	Agrega un prefijo a la URL en mayúsculas del repositorio
`APP_NAME_ID`	`my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}`	Crea un nombre de aplicación que incluya la URL del repositorio y los primeros siete caracteres del ID de carga útil.

¿Qué sigue?

Obtén más información sobre cómo sustituir valores de variables.
Obtén más información sobre cómo crear un archivo de configuración de compilación básico.
Obtén más información sobre cómo crear y administrar activadores de compilación.
Obtén más información sobre cómo ejecutar compilaciones de forma manual.