Integra el backend de tu aplicación

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.

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 obtener tu solución.

  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_CHANGE.

    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 la solución, 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": "...",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

En el ejemplo anterior, USER_ACCOUNT_ID es el ID de cuenta creado por Google Cloud Marketplace.

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ó de forma correcta, la aplicación debe llamar a la API de adquisición y también 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'}

En la que YOUR_PARTNER_ID es un ID que se te asigna cuando el Ingeniero socio habilita el acceso a la API de Partner Procurement.

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.

Crea una autorización

Cuando los clientes eligen un plan de precios para el software, Google crea una autorización, que indica que el cliente compró la solución en Google Cloud Marketplace.

Cuando un cliente elige un plan, se envía el siguiente mensaje de Pub/Sub a tu aplicación:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "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

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",
  "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 cancelled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "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",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "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 sus planes de precios.
ENTITLEMENT_ACTIVEIndica que el plan elegido de un cliente ahora está activo.
ENTITLEMENT_PLAN_CHANGE_REQUESTEDIndica que un cliente eligió un plan nuevo.
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_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 solución, debes informar el uso de la aplicación a la API de Control de servicios.

El Ingeniero socio crea un servicio que corresponde a la solución y le otorga a acceso a tu cuenta de servicio para informar el uso de ese servicio.

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

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 un Operation, que contiene un MetricValueSet para tus métricas de precios. El Operation también incluye un campo consumerId, que se establece en el objeto USAGE_REPORTING_ID desde la autorización.

El siguiente es un ejemplo de un informe de uso de example-messaging-service que envía información sobre el almacenamiento que usa 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" }]
    }]
  }]
}

Debes informar el uso de la aplicación por hora. Verifica que startTime y endTime para el uso sean precisos. Si se inhabilitó el servicio del usuario antes de la startTime, la API services.check envía un error en el objeto checkErrors[] y no se cobra al cliente por el período.

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