Esta página se ha traducido con Cloud Translation API.

Usar vinculaciones de carga útil y expansiones de parámetros bash en sustituciones

En esta página se explica cómo usar vinculaciones de carga útil y aplicar expansiones de parámetros bash a variables de sustitución asociadas a tu activador de compilación. Si no sabes cómo usar variables de sustitución en la configuración de compilación, consulta Sustituir valores de variables.

Cloud Build te permite almacenar partes de la carga útil del evento de tu activador como una variable de sustitución. La carga útil de un evento es el cuerpo del evento que invoca un activador. Las variables asociadas a una carga útil se denominan enlaces y están disponibles para las compilaciones invocadas por eventos push y pull. Los enlaces te permiten acceder a datos adicionales relacionados con tu compilación, como el idioma asociado a tu código fuente y el autor de una solicitud de extracción.

Cloud Build también permite a los usuarios aplicar expansiones de parámetros de bash a los valores de las variables de sustitución. Las expansiones de parámetros de Bash te permiten manipular cadenas asociadas a variables. Puedes manipular cadenas poniendo letras en mayúsculas o sustituyendo una subcadena.

Puedes usar vinculaciones de carga útil y aplicar expansiones de parámetros bash al definir o actualizar 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 expansiones de parámetros de bash al ejecutar compilaciones manuales.

Vinculaciones de carga útil

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

Puede acceder a la información de una carga útil de evento mediante un prefijo designado, que representa la raíz de la carga útil del evento. Empezando por el prefijo, puedes usar la sintaxis JSONPath para acceder a la carga útil y extraer datos de ella. Los siguientes prefijos de carga útil están disponibles en función del tipo de evento:

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

También están disponibles los valores de las variables integradas is_collaborator y perm_level para cualquier evento asociado a la aplicación de GitHub. El estado del usuario se comprueba en los eventos push y pull mediante los valores de las 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 de variables en el activador cuando el 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)`	Devuelve `true` si el usuario es colaborador.

Puedes usar los valores de las variables is_collaborator y perm_level para los eventos push, los eventos de solicitud de extracción y los eventos de solicitud de extracción protegidos por un comentario. No es necesario añadir un prefijo a estos valores de variables.

Crear sustituciones con vinculaciones de carga útil

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

Abre la página Activadores.
Si no has creado ningún activador de compilación, haz clic en Crear activador. De lo contrario, selecciona un activador.
En Variables de sustitución, haga clic en Añadir variable.
Añade un nombre a la Variable siguiendo la convención que se describe a continuación:
- Las sustituciones deben empezar por un guion bajo (_) e incluir solo letras mayúsculas y números (de acuerdo con la expresión regular [A-Z0-9_]+). De esta forma, se evitan conflictos con las sustituciones integradas.
- El número de parámetros está limitado a 100. La longitud de una clave de parámetro es de 100 bytes como máximo y la de un valor de parámetro, de 4000 bytes.
Para obtener más información sobre cómo definir y usar sustituciones definidas por el usuario, consulte Usar sustituciones definidas por el usuario.

Añada un valor a su variable con un prefijo admitido.

Si tu código fuente está en GitHub, puedes consultar la información de tu carga útil de eventos en variables de sustitución mediante enlaces 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, el prefijo push del 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
`_PUSH_NAME`	`$(push.repository.name)`	Obtiene el nombre del repositorio asociado al evento de envío.
`_COMMITS`	`$(push.commits)`	Obtiene la matriz de objetos de confirmación que describe 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 idioma del código fuente incluido en el envío.

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

Para acceder a la carga útil de JSON de un evento de solicitud de extracción, usa el prefijo pull_request o body. En el siguiente ejemplo, el prefijo pull_request del 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
`_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 en la que se combinó la solicitud de extracción.

Para ver una lista de los 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 del 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 a 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 a la confirmación.
`_COMMIT_DATE`	`$(commit.commit.committer.date)`	Obtiene la fecha asociada a la confirmación.
`_COMMIT_ADDITIONS`	`$(commit.files['*'].additions)`	Obtiene el número de adiciones asociadas a los archivos de la confirmación.

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

Si habilitas Control de comentarios en un activador que se invoca mediante una solicitud de extracción, el evento que invoca al activador es IssueCommentEvent y el prefijo asociado es issue_comment. En los siguientes ejemplos, el prefijo issue_comment del 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
`_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.).
`_LABELS`	`$(issue_comment.issue.labels)`	Obtiene la lista de etiquetas asociadas a 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 ver una lista de los 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 en variables de sustitución mediante enlaces de carga útil. Para acceder a la carga útil de JSON de un evento push, usa el prefijo csr o body. En el ejemplo siguiente, el prefijo csr del 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
`_REPO_NAME`	`$(csr.name)`	Obtiene el nombre de tu repositorio.
`_REPO_URL`	`$(csr.url)`	Obtiene la URL de tu repositorio.
`_CREATED_REPO`	`$(csr.createRepoEvent)`	Indica si un usuario ha creado un repositorio.
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	El nombre de la ref (por ejemplo, "refs/heads/primary-branch").

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

Expansiones de parámetros de Bash

Puedes aplicar expansiones de parámetros bash a variables predeterminadas y variables definidas por el usuario. Entre las operaciones admitidas se incluyen la sustitución de subcadenas, el corte de cadenas y el uso de mayúsculas. Por ejemplo, puede que quieras sustituir una subcadena en una variable predeterminada y usar la variable como etiqueta de imagen.

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

Expansiones de Bash	Descripción
`${var}`	Expande el valor de cadena almacenado en `var`
`${var^}`	Pone en mayúscula el primer carácter de la cadena.
`${var^^}`	Pone en mayúsculas todos los caracteres de la cadena.
`${var,}`	Convierte a minúsculas el primer carácter de la cadena.
`${var,,}`	Convierte todos los caracteres de la cadena en minúsculas.
`${var:position}`	Quita los primeros `position` caracteres de la cadena.
`${var:position:length}`	Corta la cadena empezando por el valor numérico especificado en `position` e incluye hasta el valor numérico especificado en `length`.
`${var/substring/replacement}`	Sustituye la instancia situada más a la izquierda del valor especificado en `substring` por el valor especificado en `replacement`.
`${var//substring/replacement}`	Sustituye todas las instancias del valor especificado en `substring` por el valor especificado en `replacement`.
`${var/#substring/replacement}`	Sustituye la primera instancia del valor especificado en `substring` por el valor especificado en `replacement` solo si `substring` es un prefijo de `var`.
`${var/%substring/replacement}`	Sustituye la última instancia del valor especificado en `substring` por el valor especificado en `replacement` solo si `substring` es un sufijo de `var`.
`${#var}`	Obtiene la longitud de la cadena.
`${var:-default}`	Evalúa `var` como `default`, a menos que `var` ya esté definido.

También puedes especificar patrones que coincidan con las siguientes expansiones de parámetros de bash:

Expansiones de Bash	Descripción
`${var#pattern}`	Quita los caracteres de la parte inicial de una cadena hasta la primera instancia del `pattern` especificado (inclusive).
`${var##pattern}`	Quita los caracteres de la parte izquierda de una cadena hasta la instancia situada más a la derecha del `pattern` especificado (inclusive).
`${var%pattern}`	Quita caracteres de la parte derecha de una cadena hasta la primera instancia del `pattern` especificado (inclusive).
`${var%%pattern}`	Quita los caracteres de la parte final de una cadena hasta la primera instancia (incluida) del `pattern` especificado.

Entre los patrones que puedes especificar se incluyen los siguientes:

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

Aplicar expansiones de parámetros bash

Para aplicar una expansión de parámetros bash a una variable de sustitución integrada o definida por el usuario, siga estos pasos:

Abre la página Activadores.
Si no has creado ningún activador de compilación, haz clic en Crear activador. De lo contrario, selecciona un activador.
En Variables de sustitución, haga clic en Añadir variable.
Añade un nombre a la Variable siguiendo la convención que se describe a continuación:
- Las sustituciones deben empezar por un guion bajo (_) e incluir solo letras mayúsculas y números (de acuerdo con la expresión regular [A-Z0-9_]+). De esta forma, se evitan conflictos con las sustituciones integradas.
- El número de parámetros está limitado a 100. La longitud de una clave de parámetro es de 100 bytes como máximo y la de un valor de parámetro, de 4000 bytes.
Para obtener más información sobre cómo definir y usar sustituciones definidas por el usuario, consulte Usar sustituciones definidas por el usuario.

Añada un valor a su variable aplicando una expansión de parámetros de Bash compatible a una variable de sustitución integrada u otra variable de sustitución definida por el usuario.

En el ejemplo siguiente, la variable de sustitución integrada $BRANCH_NAME tiene el valor predeterminado 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`	Convierte todos los caracteres de la cadena a minúsculas.
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#v2}`	`feature_secret_project`	Elimina todos los caracteres de la parte derecha de la cadena que coincidan con el patrón especificado.
`_BRANCH_NO_PREFIX`	`${_BRANCH_NO_SUFFIX#*_}`	`secret_project`	Elimina todos los caracteres hasta el primer guion bajo.
`_BRANCH_FOR_IMAGE_NAME`	`${_BRANCH_NO_PREFIX//_/-}`	`secret-project`	Sustituye todos los guiones bajos por un guion.
`_IMAGE_NAME`	`my-app-${_BRANCH_FOR_IMAGE_NAME}-prod`	`my-app-secret-project-prod`	Construye el nombre de la imagen usando la variable `_BRANCH_FOR_IMAGE_NAME` definida arriba.

Supongamos que _IMAGE_NAME se define en tu activador como el valor especificado en la tabla anterior, my-app-secret-project-prod. Este valor ahora sustituirá cualquier definición de _IMAGE_NAME en el archivo de configuración de compilación. En el siguiente ejemplo, el valor de la variable especificada para _IMAGE_NAME (my-app-secret-project-prod) sustituye al valor predeterminado de _IMAGE_NAME (test-image) cuando se invoca el activador de compilació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, que en el ejemplo anterior tiene el valor true, permite que se interpreten las expansiones de parámetros de bash. Si la compilación se invoca mediante un activador, el campo dynamicSubstitutions siempre se define como true y no es necesario especificarlo en el archivo de configuración de la compilación. Si la compilación se invoca manualmente, debes asignar el valor true al campo dynamicSubstitutions para que las expansiones de parámetros de Bash se interpreten al ejecutar la compilación.

Usar expansiones de parámetros bash con vinculaciones de cargas útiles

Puedes aplicar expansiones de parámetros bash a variables asociadas a vinculaciones de carga útil. Para ello, crea una variable que haga referencia a la variable que contiene tu vinculación o encadena vinculaciones con expansiones de parámetros bash. En la siguiente tabla se muestran ejemplos de cómo puedes usar la expansión de parámetros 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 bash para poner en mayúsculas todos los caracteres de la URL.
`_APP_NAME`	`my-app-${_URL_CAPITAL}`	Añade un prefijo a la URL del repositorio en mayúsculas.
`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 siete primeros caracteres del ID de la carga útil.

Siguientes pasos

Consulte cómo sustituir valores de variables.
Consulta cómo crear un archivo básico de configuración de versiones.
Consulta cómo crear y gestionar activadores de compilación.
Consulta cómo ejecutar compilaciones manualmente.