Llama a las APIs desde un proyecto de Google Cloud

1. Antes de comenzar

En este codelab, se muestra cómo crear un proyecto de Google Cloud y, luego, llamar a las APIs de Google Cloud desde ese proyecto.

Requisitos previos

• Capacidad para navegar por la consola de Google Cloud

Qué aprenderás

• Cómo crear un proyecto de Google Cloud
• Cómo configurar una cuenta de facturación
• Cómo configurar Cloud Shell
• Cómo habilitar una API
• Cómo autorizar una API con una clave de API
• Cómo autorizar una API con una cuenta de servicio

Requisitos

• Una Cuenta de Google, como una cuenta de Gmail o una cuenta de Google Workspace
• Acceso a una cuenta de Facturación de Cloud o a una tarjeta de crédito para registrarte en el programa de prueba gratuita

2. Prepárate

En esta sección, se muestra cómo crear un proyecto de Google Cloud, configurar una cuenta de facturación y configurar Cloud Shell.

Crea un proyecto de Google Cloud y configura una cuenta de facturación

Nota: Si aún no tienes una cuenta de Gmail o una cuenta de Google Workspace, primero debes crear una.

1. Accede a la consola de Cloud y selecciona o crea un proyecto.

Advertencia: Si reutilizas un proyecto y completas este codelab, es posible que permitas que algunos usuarios accedan a los recursos de ese proyecto si no los desactivas cuando termines.

Recuerda el ID del proyecto que aparece en el campo Nombre del proyecto. El ID es un nombre único en todos los proyectos de Google Cloud (el nombre anterior ya se encuentra en uso) y se menciona más adelante en este codelab como PROJECT_ID.

Nota: Si usas una cuenta de Gmail, puedes dejar la ubicación predeterminada como Sin organización. Si usas una cuenta de Google Workspace, elige una ubicación adecuada para tu organización.

2. A continuación, habilita la facturación en la consola de Cloud para usar los recursos de Google Cloud.

Aunque este codelab no debería costar mucho, si es que cuesta algo, sigue las instrucciones de la sección Limpieza para cerrar los recursos y evitar costos más allá de este codelab. Ten en cuenta que los usuarios nuevos de Google Cloud son aptos para obtener la prueba gratuita de USD 300.

Configura Cloud Shell

En este codelab, usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud. Cloud Shell es una máquina virtual basada en Debian que incluye todas las herramientas de desarrollo que necesitas. Ofrece un directorio principal persistente de 5 GB, lo que mejora considerablemente el rendimiento de la red y la autenticación. Esto significa que todo lo que necesitas para este codelab es un navegador.

Para activar Cloud Shell desde Cloud Console, haz lo siguiente:

1. Haz clic en Activar Cloud Shell.

El aprovisionamiento y la conexión al entorno pueden tardar unos minutos.

Una vez que te conectes a Cloud Shell, deberías ver que ya te autenticaste y que el proyecto ya se configuró con tu PROJECT_ID.

2. Genera una lista de cuentas con credenciales:

gcloud auth list

Deberías ver el siguiente resultado:

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

Nota: La herramienta de CLI de gcloud viene preinstalada en Cloud Shell y te ayuda a crear y administrar recursos de Google Cloud. Para obtener más información, consulta la descripción general de la herramienta de gcloud.

3. Para ver una lista de tus proyectos, ingresa este comando.

gcloud config list project

Deberías ver el siguiente resultado:

[core]
project = <PROJECT_ID>

Si, por algún motivo, el proyecto no está configurado, ejecuta este comando para configurarlo.

gcloud config set project <PROJECT_ID>

El PROJECT_ID es el ID que usaste en los pasos de configuración. También puedes buscarlo en el panel de la consola de Cloud:

Cloud Shell también configura algunas variables de entorno de forma predeterminada, lo que puede resultar útil cuando ejecutas comandos futuros.

4. Para ver el ID de tu proyecto, ingresa el siguiente comando.

echo $GOOGLE_CLOUD_PROJECT

Deberías ver el siguiente resultado:

<PROJECT_ID>

5. Establece la zona predeterminada y la configuración del proyecto.

gcloud config set compute/zone us-central1-f

Puedes elegir una variedad de zonas diferentes. Para obtener más información, consulta Regiones y zonas.

Nota: Cuando ejecutas la herramienta de CLI de gcloud en tu máquina, la configuración establecida se mantiene para todas las sesiones. Sin embargo, en Cloud Shell, debes configurar estos parámetros para cada sesión nueva o reconexión.

3. Llama a una API desde un proyecto

En este codelab, se muestra cómo usar una API de ejemplo (la API de Natural Language) para encontrar entidades (como personas, lugares y eventos) en el texto y cómo aproximar la opinión (nivel de favorabilidad) de ese texto. Aprenderás a hacer lo siguiente:

• Habilita las API de Google Cloud
• Obtén autorización para la API con claves de API y cuentas de servicio.
• Llama a la API con curl y las bibliotecas cliente.

Habilitar una API

1. Selecciona APIs & Services en el menú principal de Cloud Console.

2. Selecciona + HABILITAR APIS Y SERVICIOS en la parte superior de la pantalla.

3. En este punto, puedes filtrar y explorar las APIs, o bien ir directamente a una API con el cuadro de Búsqueda. Busca Natural Language y selecciona API de Cloud Natural Language.

4. Haz clic en PROBAR ESTA API.

Si no se muestra el botón TRY THIS API, haz clic en uno de los métodos que se indican para probarlo.

Crea una clave de API

Como usas curl para enviar una solicitud a la API de Natural Language, debes generar una clave de API para pasar la URL de tu solicitud.

1. En la consola de Cloud, selecciona Menú de navegación > APIs y servicios > Credenciales.

2. Haz clic en CREAR CREDENCIALES y, luego, selecciona Clave de API:

3. Copia la clave de API que se generó y, luego, haz clic en Cerrar.

Usa la clave de API para llamar a la API

1. En la línea de comandos de Cloud Shell, exporta tu clave de API.

export API_KEY=<YOUR_API_KEY>

Reemplaza <YOUR_API_KEY> por la clave que generaste antes.

2. Crea una solicitud para la API en el editor de Cloud Shell o con un editor de Linux, como Vim o Emacs. Puedes encontrar los detalles de los parámetros en Method: documents.analyzeEntities. Guarda el resultado en un archivo llamado request.json:

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}

3. Llama a la API con la información de la solicitud.

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. Vuelve a ejecutar el comando, redirecciona el resultado a un archivo y examina el resultado. Los detalles del resultado del archivo JSON también se encuentran en Method: documents.analyzeEntities.
5. Para cambiar el texto que se analizará en el archivo request.json, reemplaza el valor content por el texto que elijas.

4. Autoriza con una cuenta de servicio

A menudo, se prefieren las cuentas de servicio a las claves de API, ya que proporcionan autenticación y autorización. Puedes considerar las cuentas de servicio como direcciones de correo electrónico para tu app.

1. Vuelve a la sección Credenciales del menú APIs & Services.
2. Selecciona Crear credenciales, pero, esta vez, selecciona Cuenta de servicio.

3. Proporciona un nombre de cuenta de servicio que describa su propósito, como "Natural Language Service Account". El sistema sugerirá un ID. También puedes agregar una descripción. A medida que obtengas más información sobre las cuentas de servicio, les otorgarás acceso a los proyectos y a los usuarios, pero, por ahora, haz clic en Listo para crear la cuenta de servicio.
4. Para crear un par de claves que use la cuenta de servicio, haz clic en para editar la cuenta de servicio.

Se mostrarán los detalles de tu cuenta de servicio.

5. Copia la dirección de correo electrónico de la cuenta de servicio y vuelve a Cloud Shell.
6. En Cloud Shell, crea un par de claves para tu cuenta de servicio y establece una variable de entorno para que apunte a él:

gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

Google Cloud usa esta variable de entorno para encontrar las credenciales, por lo que no es necesario incluirlas en la llamada a la API.

7. Ahora puedes llamar a la API con el siguiente comando:

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

El resultado debería ser el mismo que antes.

Muchas APIs tienen bibliotecas cliente extensas para extraer estos detalles. Para obtener más información sobre las bibliotecas cliente, consulta Bibliotecas cliente de Cloud. También puedes leer la documentación de las APIs que usas para ver qué bibliotecas cliente están disponibles para ellas.

5. Limpia

No se recomienda tener una clave de API sin restricciones para los proyectos. Si alguien obtiene acceso a ella, podrá usarla sin necesidad de autenticarse.

Para borrar esta clave de API, sigue estos pasos:

1. Haz clic en Menú de navegación > APIs y servicios > Credenciales.
2. En Claves de API, selecciona la clave que deseas borrar y, luego, haz clic en Borrar.
3. Del mismo modo, en lugar de preocuparte por que tu clave privada de la cuenta de servicio no esté protegida, en Cuentas de servicio, selecciona la cuenta de servicio que deseas borrar y, luego, haz clic en Borrar.

6. Felicitaciones

¡Felicitaciones! Aprendiste a crear un proyecto de Google Cloud y a llamar a una API desde el proyecto.