Integrar asistencia en tu solución

En esta sección, se describe el flujo de trabajo de asistencia cuando quieres proporcionar asistencia como parte de tu producto.

Tu sistema debe estar integrado con el servicio de Google para que puedas proporcionar asistencia a los clientes que compraron tus productos en Google. La integración se basa en que Google aprovisione estos elementos:

  • Una clave que usarás para verificar si un usuario cumple con los criterios de elegibilidad de asistencia como parte del proceso de registro.

  • Una API (las API de suscripciones) a la que puedes pasar la clave para sondear de forma periódica el estado de la elegibilidad de asistencia de un usuario.

Obtén el ID de asistencia del usuario

La integración de la asistencia se centra en un ID de cuenta externo que tus usuarios ven como su ID de asistencia.

Para obtener el ID de asistencia de tus usuarios, crea un flujo de trabajo de asistencia y proporciona una URL para el inicio del flujo de trabajo. Luego, Google te envía el ID de cuenta externo en la URL.

Si implementas el flujo de trabajo de asistencia, debe aceptar el ID de cuenta externo como parte de la URL. El ID de cuenta externo puede ser parte de la ruta de la URL o un valor de parámetro de consulta, como se muestra en el ejemplo a continuación:

# External account ID in path
http://example.com/mysupportpage/{external_account_id}?someparameter=yes

# External account ID as a query parameter
http://example.com/mysupportpage?eid={external_account_id}&something_else

El texto {external_account_id} en la URL se reemplaza por el ID de la cuenta externa. Si tienes varios productos enumerados en Google Cloud Marketplace, es posible que quieras incluir un parámetro de consulta a fin de identificar el producto para el que es la URL.

Usa la API de suscripciones

Una vez que tenga el ID de la cuenta externa del usuario, puede usar la API de suscripciones proporcionada por Google a fin de verificar la elegibilidad de asistencia para su cuenta en cualquier momento. La elegibilidad se rastrea con una búsqueda a entidades llamadas suscripciones.

Cada suscripción tiene un número de ID de suscripción único, y se crea una suscripción única por cliente para cada producto que enumeres en Cloud Marketplace, por lo que también puedes consultar una suscripción por ID de suscripción a fin de obtener detalles adicionales. sobre el historial de un cliente con tu producto, como su fecha de inicio, fecha de finalización, etcétera.

Acceder a la API de suscripciones

La API de suscripciones es una API no pública, por lo que los desarrolladores y los proyectos que necesitan acceso deben estar permitidos.

Para incluir el permiso y la lista de usuarios permitidos, sigue estos pasos:

  1. Envíe una lista de direcciones de correo electrónico para desarrolladores que necesiten acceder a la documentación de la API a su Ingeniero socio de Google Cloud Marketplace o a cloud-partner-onboarding@google.com. Estas deben ser las direcciones de correo electrónico exactas que los desarrolladores utilizarán para iniciar sesión http://console.developers.google.com. Estos desarrolladores se agregarán al grupo que otorga permiso para acceder a la documentación de la API de suscripciones.

  2. Envía el ID del proyecto de tu producto a tu Ingeniero socio de Google Cloud Marketplace y solicita que se le otorgue permiso para llamar a la API. Se pueden incluir varios proyectos si es necesario.

  3. Habilite la API de Facturación de Cloud mediante la expansión del menú cerca del lado superior izquierdo de https://console.developers.google.com y haga clic en API y servicios, luego, busque y habilite la API de Facturación de Cloud.

  4. Cree una cuenta de servicio OAuth2 asociada con su proyecto y envíe la dirección de correo electrónico de esta cuenta a su Ingeniero socio de Google Cloud Marketplace. Este usuario podrá enumerar todas las suscripciones por ti y se usará a fin de autorizar todas las solicitudes, excepto las realizadas mediante la solicitud del permiso del cliente con un diálogo OAuth.

Debido a que la API de suscripciones no es una API pública, no está incluida en la biblioteca cliente de Python de forma predeterminada. Si planea utilizar la biblioteca del cliente Python con esta API, también debe comunicarse con su Ingeniero socio de Google para obtener ayuda para acceder al archivo de descubrimiento.

En el ejemplo de inicialización a continuación, se establece el nombre del archivo de detección en la ruta que se descargó el archivo de detección.

   # Load the local copy of the discovery document
   f = file(os.path.join(os.path.dirname(__file__),
         "cloudbilling-subscriptions_discovery.json"), "r")
   discovery = f.read()
   f.close()

   # Construct a service from the local documents
   service = build_from_document(discovery,
         base="https://www.googleapis.com/",
         http=http)

La biblioteca cliente también es compatible con la autenticación de OAuth para las credenciales del cliente y las cuentas de servicio de OAuth2. Para obtener más información, consulta la documentación de OAuth 2.0 en la biblioteca cliente de la API de Google para Python.

Consulta la API de suscripciones

Si deseas obtener permiso para acceder a los datos de suscripciones, necesitas crear una cuenta de servicio de OAuth2 y, también, indicar la cuenta que deseas usar para autorizar las solicitudes de la API. Luego, Google otorgará acceso a esa cuenta de servicio a fin de leer las suscripciones de todos los clientes. Si deseas obtener más información, consulta Usa OAuth 2.0 para aplicaciones de servidor a servidor.

La API es una API de REST de solo lectura que devuelve recursos de suscripción, que se pueden utilizar para obtener la siguiente información:

  • nombre: un identificador para un solo recurso de suscripción
  • externalAccountId: un identificador para una sola cuenta de facturación.
  • versión: un número de versión que se actualiza cada vez que se modifica el registro. Se puede usar para detectar fácilmente cualquier cambio desde la última lectura.
  • estado: uno de los valores siguientes:
    • ACTIVO: en la actualidad, la suscripción está activa y el cliente debe ser capaz de recibir tu asistencia. Una suscripción se considera activa si la cuenta ha tenido una VM activa en los últimos 30 días.
    • COMPLETE: la suscripción ya no está activa, porque el cliente no tiene ninguna VM activa en ejecución con tu producto y no tiene los últimos 30 días.

  • subscribedResources: una lista de recursos cubiertos por esta suscripción.
  • startDate: la fecha en que comenzó la suscripción, formateada como una cadena en formato RFC 3339.
  • endDate: la fecha de finalización de la suscripción (si ha finalizado), formateada como una cadena en formato RFC 3339.
  • Etiqueta para la última marca de tiempo de monitoreo de funcionamiento (con clave): el valor de esta etiqueta indica la marca de tiempo del último ritmo cardíaco de cualquier VM que ejecuta el producto. Por ejemplo: cloudmarketplacepartner.googleapis.com/last_heartbeat_us

Cuando un cliente hace clic en el vínculo para acceder a su sitio desde Google Cloud Console, debe verificar que el cliente esté autorizado para usar el vínculo mediante las siguientes solicitudes:

  1. Enumera las suscripciones para los ID de cuenta externos.
  2. Cómo buscar la suscripción activa del producto
  3. Obtén la información de suscripción con el ID de suscripción.

Si el cliente es un usuario autorizado, la solicitud será exitosa. Si el cliente no es un usuario autorizado para la suscripción, la llamada mostrará un código de error no autorizado (HTTP 403).

Esto requiere que solicites el permiso del cliente para leer tus datos de suscripciones durante el proceso de registro mediante un flujo de solicitudes de OAuth estándar.

Las solicitudes posteriores para actualizar los datos de suscripción usan tu cuenta de servicio creada antes.

Flujo del registro de atención al cliente

Después de que un cliente implementa tu producto mediante Cloud Marketplace o las API de Compute Engine, Google Cloud Console le muestra un vínculo a tu sitio a fin de completar el registro para la asistencia. El vínculo incluirá el ID de cuenta externo que se usará para esa cuenta.

Tu sitio debe permitir al cliente crear una cuenta y proporcionar la información de contacto que necesite. Google no proporcionará información de identificación personal sobre el cliente. Tú eres responsable de mantener una asignación entre su cuenta y el ID de cuenta externo proporcionado por Google.