Integrar el backend de tu app

En esta sección, se describen los pasos para integrar el backend de la aplicación en Google Cloud Marketplace. Con esta integración, puedes administrar cuentas de usuario y autorizaciones, que indican que los usuarios compraron tu producto en Google Cloud Marketplace. Si eliges un modelo de precios basado en el uso, también integras tu backend para informar el uso a Google.

Si deseas ver un ejemplo de integración de una aplicación básica con Google Cloud Marketplace y una explicación del código de muestra, consulta el codelab para integrar un servicio administrado.

Para ver el código de muestra que se usa en el codelab, consulta el repositorio de GitHub.

Antes de comenzar

  • Configura el acceso a la API de Partner Procurement de Cloud Commerce, como se describe en Integra tu aplicación: configuración.
  • Si eliges un esquema de precios basado en el uso, verifica que tu Ingeniero socio haya creado un servicio en el que puedas informar el uso. Este servicio se muestra en el campo Dominio de servicio de la sección de integración de facturación de Producer Portal.

Crea una cuenta de servicio

Para integrar tu producto con Google Cloud, debes crear una cuenta de servicio en el proyecto que usas para tu producto. Tu app usa esta cuenta de servicio para interactuar con las API de socios de Google Cloud Marketplace y obtener información sobre las compras de los usuarios.

Te recomendamos usar Producer Portal para crear y vincular tus cuentas de servicio.

Si usas el Portal para socios, tu Ingeniero socio otorga la función de suscriptor de Pub/Sub a esta cuenta de servicio. Para obtener pasos detallados sobre cómo crear una cuenta de servicio, consulta Crea y administra cuentas de servicio.

Usa Producer Portal para integrar el backend de tu app

Para acceder a toda la información que necesitas a fin de integrar el backend de tu app con Google Cloud Marketplace desde una ubicación, como tus cuentas de servicio y los identificadores de nivel del plan, puedes usar la sección del Producer Portal INTEGRACIÓN DE FACTURACIÓN.

El vínculo directo al Producer Portal es el siguiente:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Para acceder a la sección INTEGRACIÓN DE FACTURACIÓN:

  1. En la lista de productos, haz clic en el nombre de tu producto.

  2. En la página Descripción general de tu producto, ve a la sección Integración técnica y haz clic en INTEGRACIBILLINGN DE FACTURACIBILLINGN.

Crea y vincula cuentas de servicio en Producer Portal

Puedes usar la sección INFORMACIÓN DE FACTURACIÓN en el portal productor y crear y vincular las cuentas de servicio que usas para interactuar con las API de Partner y obtener información sobre las compras de los usuarios.

El vínculo directo al Portal para socios es el siguiente:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

En los pasos siguientes, puedes usar cuentas de servicio existentes o crear cuentas de servicio nuevas. Si creas una cuenta de servicio nueva, especifica su nombre en el campo Nombre de la cuenta de servicio y su ID en el campo ID de cuenta de servicio y, luego, haz clic en CREAR Y VINCULAR.

Para vincular tus cuentas de servicio, sigue estos pasos:

  1. En la lista de productos, haz clic en el nombre de tu producto.

  2. En la página Descripción general de tu producto, ve a la sección Integración técnica y haz clic en INTEGRACIBILLINGN DE FACTURACIBILLINGN.

  3. Para integrarla a la API de Partner Procurement, en Vincular una cuenta de servicio para llamar a la API de Procurement, haz clic en AGREGAR CUENTA DE SERVICIO. Puedes ingresar una cuenta de servicio existente en el campo o crear una cuenta de servicio nueva.

  4. Para integrar tu app a Pub/Sub, en Vincular una cuenta de servicio para suscribirte al tema de Pub/Sub, haz clic en AGREGAR CUENTA DE SERVICIO. Puedes ingresar una cuenta de servicio existente en el campo o crear una cuenta de servicio nueva.

  5. Para integrarla a la API de Control de servicios, en Agregar roles/servicemanagement.serviceController a una cuenta de servicio, haz clic en AGREGAR CUENTA DE SERVICIO. Puedes ingresar una cuenta de servicio existente en el campo o crear una cuenta de servicio nueva.

Tareas de cuenta de usuario

En un nivel alto, la aplicación debe controlar la siguiente situación:

  1. Un usuario realiza una solicitud o un cambio en Google Cloud Marketplace, como registrarse para tu producto.

  2. Google Cloud Marketplace envía una notificación a tu aplicación a través de Pub/Sub, que contiene información sobre la solicitud en el campo eventType. Por ejemplo, si un usuario cambia su autorización, la eventType es ENTITLEMENT_PLAN_CHANGED.

    Consulta la lista completa de eventType posibles.

  3. Para aprobar la solicitud, tu aplicación envía una solicitud HTTP POST a la API de Partner Procurement.

En las secciones siguientes, se describen los tipos de solicitudes que pueden realizar los usuarios y que debe hacer la aplicación para controlar las solicitudes.

Para las llamadas a la API que se describen en esta sección, usa el siguiente extremo:

https://cloudcommerceprocurement.googleapis.com/

Crea una cuenta para un usuario nuevo

Cuando un usuario compra por primera vez tu producto, Google Cloud Marketplace crea un recurso de cuenta que realiza un seguimiento de la relación del usuario contigo. Cuando se crea el recurso de cuenta, recibes una notificación a través del tema de Pub/Sub que se creó para ti. El mensaje de Pub/Sub tiene el siguiente formato:

{
  "eventId": "...",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

en la que USER_ACCOUNT_ID es el ID de cuenta que creó Google Cloud Marketplace y YOUR_PARTNER_ID es un ID que se te asigna cuando el Ingeniero socio habilita el acceso a la API de Partner Procurement.

Al mismo tiempo, se dirige al usuario a la página de registro, en la que crea una cuenta en tu sistema. Para obtener información sobre la creación de la página de registro, consulta Integra el frontend de la aplicación.

Después de que el usuario se registró con éxito, la aplicación debe llamar a la API de Partner para indicar que la cuenta se aprobó. Las cuentas se crean con el estado ACCOUNT_ACTIVE, pero tienen una entrada PENDING en el campo approvals llamada signup, lo que indica que el usuario aún no se registró. Para aprobar la cuenta después de que el usuario se registró, usa la siguiente solicitud HTTP POST:

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

Para verificar el estado de una cuenta vinculada, usa la siguiente solicitud HTTP GET:

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

La respuesta está en el siguiente formato:

{
  "name": "providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID",
  "provider": "acme-services",
  "state": "ACCOUNT_ACTIVE",
  "approvals": [{
    "name": "signup",
    "state": "APPROVED",
    "updateTime": "...",
  }],
  "updateTime": "...",
  "createTime": "..."
}

Para obtener una lista de posibles estados de cuenta, consulta la referencia de la API de providers.accounts.

Administra autorizaciones

Cuando los clientes eligen un plan de precios para tu software, Google crea una autorización, que indica que el cliente compró tu producto en Google Cloud Marketplace. En esta sección, se explica cómo crear y administrar autorizaciones para tus clientes con la API de Partner Procurement.

Para obtener más información sobre cómo administrar autorizaciones, consulta la documentación de referencia.

Aprueba o rechaza una autorización

Cuando un cliente elige un plan de precios, Google Cloud Marketplace crea una autorización y envía el siguiente mensaje de Pub/Sub a tu app:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

En el ejemplo anterior, ENTITLEMENT_ID es un ID creado por Google Cloud Marketplace.

En tu sistema, actualiza la cuenta del usuario para reflejar que compró un plan. Luego, para aprobar la autorización, realiza una solicitud HTTP POST a la API de Partner Procurement y envía el ENTITLEMENT_ID que aprobaste:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

Para rechazar una autorización, usa el método reject en tu solicitud HTTP POST:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject

Cambia el plan de autorización

De acuerdo con la manera en que configures los planes de precios, los clientes podrían cambiar sus planes. Si un cliente selecciona un plan de precios nuevo, recibirás un mensaje de Pub/Sub en el siguiente formato:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
  },
}

Para aprobar el cambio de plan, realiza la siguiente solicitud HTTP POST a la API de socio:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

El cuerpo de la solicitud debe contar con el plan que se aprueba:

{
  "pendingPlanName": PLAN_NAME
}

Después de que se apruebe el cambio, recibirás otro mensaje de Pub/Sub cuando entre en vigencia. En el mensaje, el campo eventType cambia a ENTITLEMENT_PLAN_CHANGED. Para verificar el estado de un plan, realiza la siguiente solicitud HTTP GET a la API de Partner Procurement.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

La respuesta es similar a la siguiente, el campo state indica si el plan nuevo está activo o si el cambio del plan todavía está pendiente.

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

Envía un mensaje de estado a los usuarios

Si el tiempo entre que un usuario elige un plan de precios y que el backend aprueba la autorización es de unas horas o mayor, recomendamos que envíes un mensaje de estado a los usuarios. En el mensaje, indica el progreso de la aprobación y, si está disponible, cuándo esperas que se complete.

Para proporcionar un mensaje de estado, realiza la siguiente solicitud HTTP POST a la API de Procurement:

POST v1/providers/your-partner-id/entitlements/entitlement_id:updateUserMessage

En el cuerpo de la solicitud, proporciona el texto del mensaje, similar al siguiente ejemplo:

{
  "message": "Approval expected in 2 days"
}

Cancela autorizaciones

Si un usuario decide cancelar la autorización, recibirás una notificación de Pub/Sub. De igual manera que cuando se cambia un plan, la cancelación se efectuará al final del ciclo de facturación actual.

La notificación está en el siguiente formato:

{
  "eventId": "...",
  // If the entitlement is canceled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "cancellationDate": "...",
    "updateTime": "..."
  },
}

Borra una autorización

Si un usuario realiza una solicitud directa o si abandona la plataforma de Google, se cancelan y se borran las autorizaciones junto con la cuenta de ese usuario. Para proteger la privacidad del usuario, debes borrar sus datos de los servidores cuando recibes la notificación.

Cuando se cancelan las autorizaciones y se borra la cuenta, recibirás notificaciones similares a las que se muestran a continuación:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

Lista de tipos de eventos para tareas de la cuenta

A continuación, se muestra una lista de los eventType que tu app podría recibir en mensajes de Pub/Sub:

eventTypeDescripción
ACCOUNT_CREATION_REQUESTEDObsoleta
ACCOUNT_ACTIVEIndica que se creó la cuenta del cliente.
ACCOUNT_DELETEDIndica que la cuenta del cliente se borró de los sistemas de Google Cloud.
ENTITLEMENT_CREATION_REQUESTEDIndica que un cliente seleccionó uno de tus planes de precios. Esto también activa un nuevo evento ENTITLEMENT_CREATION_REQUESTED cada 24 horas hasta que tomes las medidas sobre la solicitud del cliente.
ENTITLEMENT_ACTIVEIndica que el plan elegido de un cliente ahora está activo.
ENTITLEMENT_PLAN_CHANGE_REQUESTEDIndica que un cliente eligió un plan nuevo. Esto también activa un nuevo evento de ENTITLEMENT_PLAN_CHANGE_REQUESTED cada 24 horas hasta que tomes las medidas correspondientes a la selección del cliente.
ENTITLEMENT_PLAN_CHANGEDIndica que el cambio de plan del cliente está aprobado y que los cambios entraron en vigencia.
ENTITLEMENT_PLAN_CHANGE_CANCELLEDIndica que se canceló el cambio de plan de un cliente, ya sea porque no se aprobó o porque volvió a su plan anterior.
ENTITLEMENT_PENDING_CANCELLATIONIndica que un cliente canceló su plan y la cancelación está pendiente hasta el final del ciclo de facturación.
ENTITLEMENT_CANCELLATION_REVERTEDIndica que se revocó la cancelación pendiente de un cliente. Ten en cuenta que las cancelaciones no se pueden revertir después de su finalización.
ENTITLEMENT_CANCELLEDIndica que se canceló el plan de un cliente.
ENTITLEMENT_CANCELLINGIndica que el plan del cliente está en proceso de cancelación.
ENTITLEMENT_RENEWEDIndica que la autorización de un cliente se renovó para otro período. No es necesario que realice ninguna acción para finalizar la renovación.
ENTITLEMENT_OFERTA_ENDEDIndica que finalizó la oferta privada de un cliente. Si se canceló la autorización del cliente, se activará un evento ENTITLEMENT_CANCELLED distinto. Si la autorización del cliente todavía está activa, su plan vuelve a los precios sin descuento.
ENTITLEMENT_DELETEDIndica que la información sobre el plan de un cliente se borró de Google Cloud Marketplace.

Informa el uso a Google (para precios basados en el uso)

Si eliges precios basados en el uso para tu producto, debes informar el uso de la app a la API de Control de servicios.

Para obtener más información sobre Control de servicios, consulta la guía de introducción.

Si tienes acceso al portal productor, te recomendamos que uses el portal productor para crear una cuenta de servicio en el Portal de productor y usarlo con Control de servicios.

Si no tienes acceso al portal productor, tu Ingeniero socio crea un servicio que corresponde a la solución y le otorga acceso a tu cuenta de servicio para informar el uso.

Cuando se crea una autorización, debes llamar a la API de Partner Procurement para recuperar un usageReportingId mediante la siguiente solicitud HTTP GET:

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

La respuesta contiene información sobre la autorización, en el siguiente formato:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

Para informar el uso, primero debes realizar una llamada a la API de services.check a fin de verificar la configuración del servicio. En la respuesta, si el objeto checkErrors[] está vacío, realiza una llamada a la API de services.report para enviar el informe de uso.

El informe de uso es una API de Control de servicios Operation. El siguiente es un ejemplo de un informe de uso para example-messaging-service que envía información sobre el almacenamiento que se usa por el cliente:

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report
{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }],
    "userLabels": {
      "cloudmarketplace.googleapis.com/resource_name": "order_history_cache",
      "cloudmarketplace.googleapis.com/container_name": "storefront_prod",
      "environment": "prod",
      "region": "us-west2"
    }
  }]
}

Donde:

  • operationId es una string única que genera la instancia de servicio. Debes usar el mismo operationId para tus operaciones check y report.

  • consumerId es el mismo que el de usageReportingId de la autorización.

  • startTime y endTime representan las horas de inicio y finalización del intervalo total para la operación report. En la mayoría de los casos, el startTime de una operación report debe tener el mismo valor que el endTime de la operación report anterior.

    Si el servicio de un cliente está inhabilitado antes del startTime de una operación report, la llamada a la API services.check envía un error en el objeto checkErrors[] y no se le cobra al cliente. para el intervalo correspondiente.

  • MetricValueSet contiene uno o varios intervalos de tiempo intermedios y los valores de métrica actualizados correspondientes. Define las métricas de tu servicio cuando eliges y envías tu modelo de precios.

    Si tienes acceso al portal productor, puedes ver y hacer referencia a los identificadores de tus métricas en la sección Integración técnica del portal productor.

  • userLabels son etiquetas creadas por el usuario, definidas como strings de clave-valor que siguen requisitos de sintaxis específicos. Estas etiquetas se reenvían a las herramientas de administración de costos de Cloud Billing para la atribución. Si quieres obtener convenciones de etiquetado recomendadas, consulta Recomendaciones para el etiquetado de uso.

Si la API services.check muestra uno o más de los siguientes errores, te recomendamos que dejes de proporcionar tu servicio al cliente hasta que se resuelva el error:

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED

Recomendaciones para el etiquetado de uso

Para una autorización determinada, todo el uso se atribuye a una sola usageReportingId. Sin embargo, en algunas situaciones, una usageReportingId se puede compartir ampliamente dentro de la organización del cliente. Para admitir la atribución de costos de granos, recomendamos que todos los servicios adjunten userLabels a los informes de uso. Las etiquetas se reenviarán a las herramientas de administración de costos de Cloud Billing, incluidos los informes de costos y las exportaciones de facturación.

Si tu servicio admite de manera nativa un concepto de etiquetas de recursos, te recomendamos reenviar esas etiquetas en tus informes de uso. Ten en cuenta que las etiquetas deberán cumplir con los requisitos de sintaxis.

Además, Google Cloud Marketplace usa las siguientes convenciones de etiquetas. Puedes usar estas etiquetas para identificar el contexto adicional de uso en tu plataforma de servicio nativa. Te recomendamos que incluyas estas etiquetas en tus informes de uso de forma predeterminada.

Clave de etiquetaValor de etiquetaDescripción>
cloudmarketplace.googleapis.com/resource_name USER_SUPPLIED El nombre del recurso asociado con una métrica de uso. Por ejemplo, si la métrica informa las cantidades de almacenamiento de la base de datos, el valor de esta etiqueta sería el nombre de la base de datos.
cloudmarketplace.googleapis.com/container_name USER_SUPPLIED El nombre de un contenedor del recurso. Por ejemplo, si un contenedor del clúster está vinculado a un recurso de base de datos, el valor de esta etiqueta sería el nombre del clúster.