Cómo sincronizar documentación personalizada a través de una API

En el portal se proporciona una API especial para sincronizar tu contenido personalizado. Para llamar a esta API, debes seguir estos pasos:

  1. Sincroniza tu contenido personalizado de manera manual al menos una vez.
  2. Crea una cuenta de servicio con la autorización y clave adecuadas.
  3. Haz una solicitud HTTP para sincronizar tu contenido.

Este documento ofrece instrucciones sobre cómo crear una cuenta de servicio y ejemplos sobre cómo hacer la solicitud con Python o mediante la línea de comandos.

Crear una cuenta de servicio autorizada

Para usar una API para sincronizar tu contenido personalizado, necesitas una cuenta de servicio con la autorización y la clave adecuadas. Para crear la cuenta de servicio, otorgarle la función adecuada y obtener el archivo de claves necesario, sigue estas instrucciones:

Console

  1. En Cloud Console, abre la página Cuentas de servicio.

    Ir a la página Cuentas de servicio

  2. Haz clic en Seleccionar un proyecto.

  3. Selecciona el proyecto y haz clic en Abrir.

  4. Haz clic en  Crear cuenta de servicio.

  5. En el campo Nombre de la cuenta de servicio, ingresa un nombre comercial para tu cuenta de servicio.

  6. Marca la casilla de verificación Proporcionar una clave privada nueva.

  7. En Tipo de clave, usa el tipo predeterminado, JSON.

  8. Haz clic en Guardar.

  9. La información de la clave se muestra en un cuadro de diálogo. Cierra el cuadro de diálogo para continuar.

  10. En Cloud Console, ve a la página Endpoints > Servicios del proyecto.

    Servicios de Endpoints

  11. Haz clic en el nombre de la API en la que necesitas sincronizar contenido personalizado para cambiar sus permisos de acceso.

  12. Si el panel lateral Permisos no está abierto, haz clic en +Permisos.

  13. Para otorgar acceso a la API a la cuenta de servicio creada, ingresa la dirección de correo electrónico de esta en el campo Agregar miembros.

  14. En la lista desplegable Seleccionar una función, haz clic en Administración de servicios y selecciona la función Editor de configuración de servicio para la cuenta de servicio.

Felicitaciones. Creaste la cuenta de servicio, descargaste su clave privada a un archivo JSON y le asignaste la función adecuada.

gcloud

  1. Ingresa el siguiente comando para mostrar los ID de tus proyectos de Google Cloud:

    gcloud projects list
    
  2. Reemplaza [YOUR_PROJECT_ID] en el siguiente comando para definir el proyecto predeterminado en el que se encuentra tu API:

    gcloud config set project [YOUR_PROJECT_ID]
    
  3. Asegúrate de que el SDK de Cloud (gcloud) esté autorizado para acceder a tus datos y servicios en Google Cloud:

    gcloud auth login
    

    Si tienes más de una cuenta, asegúrate de elegir la que está en el proyecto de Google Cloud en el que se encuentra la API. Si ejecutas gcloud auth list, la cuenta que seleccionaste se muestra como la cuenta activa para el proyecto.

  4. Para crear una cuenta de servicio, ejecuta el siguiente comando y reemplaza [SERVICE_ACCOUNT_NAME] y [Service Account to Sync Custom Content] por el nombre y el nombre comercial que quieres usar:

    gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
      --display-name "[Service Account to Sync Custom Content]"
    

    Con el comando, se asigna una dirección de correo electrónico para la cuenta de servicio en este formato:

    [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
    

    Esta dirección de correo electrónico se requiere en los comandos posteriores.

  5. Crea un archivo de claves de cuenta de servicio y reemplaza [KEY_FILE] con el nombre de archivo para tu clave:

    gcloud iam service-accounts keys create ~/[KEY_FILE] \
      --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
    
  6. Para otorgarle acceso a la API con el contenido personalizado a la cuenta de servicio, ejecuta el siguiente comando, pero reemplaza [YOUR_SERVICE_NAME] con el nombre de la API que tenga el contenido personalizado:

    gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
          --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
          --role roles/servicemanagement.configEditor
    

Envía una solicitud para sincronizar el contenido personalizado

En los siguientes ejemplos se muestra cómo hacer una solicitud para sincronizar contenido personalizado. La solicitud debería ser similar a la siguiente:

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

Reemplaza [YOUR_PROJECT_ID] y [YOUR_SERVICE_NAME] con los valores que correspondan. Cuando la solicitud se completa correctamente, la respuesta tiene un código de estado HTTP de 200.

Los siguientes ejemplos muestran cómo obtener un token de acceso de los servidores de autorización de Google y cómo usarlo para realizar la solicitud en el extremo de tu portal con Python o la línea de comandos:

Python

  1. Instala las bibliotecas de Python necesarias:
        pip install --upgrade google-auth
  2. Para crear un objeto Credentials a partir de las credenciales de la cuenta de servicio y los alcances que se requieren en el extremo, y realizar la solicitud para sincronizar el contenido, reemplaza [YOUR_PROJECT_ID], /path/to/service.json y [YOUR_SERVICE_NAME] por los valores apropiados en la siguiente secuencia de comandos:
    from google.oauth2 import service_account
    from google.auth.transport.requests import AuthorizedSession
    
    SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
    SERVICE_ACCOUNT_FILE = "/path/to/service.json"
    PROJECT_ID = "[YOUR_PROJECT_ID]"
    SERVICE_NAME = "[YOUR_SERVICE_NAME]"
    
    credentials = service_account.Credentials.from_service_account_file(
       SERVICE_ACCOUNT_FILE, scopes=SCOPES)
    authed_session = AuthorizedSession(credentials)
    endpoint =
    "https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
    result = authed_session.post(endpoint)
    print result

Línea de comandos

  1. Abre Cloud Shell o una ventana de la terminal si tienes el SDK de Cloud instalado en tu computadora Linux.
  2. Para autenticar tu cuenta de servicio, reemplaza [KEY_FILE] con la ruta de acceso al archivo de claves de tu cuenta de servicio y ejecuta el comando:
    gcloud auth activate-service-account --key-file [KEY_FILE]
  3. Obtén un token de autorización con tu cuenta de servicio:
    ACCESS_TOKEN=$(gcloud auth print-access-token)
  4. Cuando llames a la API, transfiere el valor del token como un token del portador en un encabezado de autorización. Reemplaza [YOUR_PROJECT_ID] y [YOUR_SERVICE_NAME] con los valores que correspondan:
    curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content