👨🏻‍🏫 GraphQL query для автоматической отправки подписчиков рассылки из InstaWP в Mailchimp

(Прочитайте запись блога 🚀 Автоматическая отправка подписчиков рассылки из InstaWP в Mailchimp, чтобы увидеть контекст этого запроса.)

Этот GraphQL query захватывает email посетителей, которые поставили галочку «Subscribe to mailing list» в InstaWP (при создании нового sandbox-сайта), и подписывает этот email на список Mailchimp:

query HasSubscribedToNewsletter {
  hasSubscriberOptIn: _httpRequestHasParam(name: "marketing_optin")
  subscriberOptIn: _httpRequestStringParam(name: "marketing_optin")
  isNotSubscriberOptInNAValue: _notEquals(value1: $__subscriberOptIn, value2: "NA")
  subscribedToNewsletter: _and(values: [$__hasSubscriberOptIn, $__isNotSubscriberOptInNAValue])
    @export(as: "subscribedToNewsletter")
}
 
query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   @include(if: $subscribedToNewsletter)
{
  subscriberEmail: _httpRequestStringParam(name: "email")
  
  mailchimpUsername: _env(name: "MAILCHIMP_API_CREDENTIALS_USERNAME")
    @remove
  mailchimpPassword: _env(name: "MAILCHIMP_API_CREDENTIALS_PASSWORD")
    @remove
  
  mailchimpListMembersJSONObject: _sendJSONObjectItemHTTPRequest(input: {
    url: "https://us7.api.mailchimp.com/3.0/lists/{listCode}/members",
    method: POST,
    options: {
      auth: {
        username: $__mailchimpUsername,
        password: $__mailchimpPassword
      },
      json: {
        email_address: $__subscriberEmail,
        status: "subscribed"
      }
    }
  })
}Copy

Кроме того, вы можете регистрировать подписчиков в вашем плагине рассылки для WordPress (например, Noptin или другом).

Давайте разберём, как этот GraphQL query делает своё дело.

​

Разделение GraphQL query на независимые единицы

GraphQL-документ может содержать несколько операций (queries и mutations), но выполнена будет только одна из них. Нужную указываем с помощью параметра ?operationName=... в GraphQL-эндпоинте; в противном случае будет выполнена последняя операция.

Обратите внимание, что в приведённом выше документе есть 2 операции query:

1. HasSubscribedToNewsletter
2. MaybeCreateContactOnMailchimp

URL вебхука содержит ?operationName=MaybeCreateContactOnMailchimp, поэтому именно эта операция будет выполнена.

Благодаря расширению Multiple Query Execution MaybeCreateContactOnMailchimp сначала выполнит HasSubscribedToNewsletter, как указано директивой @depends:

query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   # ...
{
  #
}Copy

Кроме того, MaybeCreateContactOnMailchimp будет выполнена условно — только если значение переменной $subscribedToNewsletter равно true:

query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   @include(if: $subscribedToNewsletter)
{
  #
}Copy

$subscribedToNewsletter — это динамическая переменная, экспортированная внутри операции HasSubscribedToNewsletter:

query HasSubscribedToNewsletter {
  # ...
  subscribedToNewsletter: _and(values: [$__hasSubscriberOptIn, $__isNotSubscriberOptInNAValue])
    @export(as: "subscribedToNewsletter")
}Copy

Таким образом, операция MaybeCreateContactOnMailchimp будет выполнена только тогда, когда пользователь поставил галочку «Subscribe to mailing list».

​

Вычисление того, поставил ли пользователь галочку

Документация по вебхуку InstaWP указывает, что данные payload содержат следующие поля (среди прочих):

• marketing_optin: Указывает, поставил ли пользователь галочку
• email: Email посетителя

Документация лишь поясняет, что поле marketing_optin имеет значение NA, когда галочка не установлена, поэтому нам придётся работать с этим.

Чтобы выяснить, поставил ли пользователь галочку, логика такова:

• Проверить, присутствует ли поле marketing_optin, и
• Проверить, что его значение не равно NA

Это вычисляется в операции HasSubscribedToNewsletter. Вот она с комментариями, объясняющими, что делает каждая строка query:

query HasSubscribedToNewsletter {
 
  # Check if field `marketing_optin` is present
  hasSubscriberOptIn: _httpRequestHasParam(name: "marketing_optin")
 
  # Get the value of field `marketing_optin`
  subscriberOptIn: _httpRequestStringParam(name: "marketing_optin")
 
  # Check if the value of the field is not "NA"
  isNotSubscriberOptInNAValue: _notEquals(value1: $__subscriberOptIn, value2: "NA")
 
  # Perform an AND operation: field present && value != "NA"
  subscribedToNewsletter: _and(values: [$__hasSubscriberOptIn, $__isNotSubscriberOptInNAValue])
    
    # Export the result under dynamic variable $subscribedToNewsletter
    @export(as: "subscribedToNewsletter")
}Copy

В этом query есть несколько интересных вещей.

​

Global Fields

Вы заметили поля, начинающиеся с _? А именно:

• _httpRequestHasParam
• _httpRequestStringParam
• _notEquals
• _and

Это глобальные поля — поля, доступные во всех типах схемы GraphQL. Глобальные поля предоставляют функциональность, а не данные, и по соглашению начинаются с _.

​

Field to Input

Вы заметили переменные, начинающиеся с $__? А именно:

• $__subscriberOptIn
• $__hasSubscriberOptIn
• $__isNotSubscriberOptInNAValue

Это динамические переменные, содержащие значение поля, объявленного перед ними в рамках той же операции. Например, переменная $__subscriberOptIn содержит значение поля subscriberOptIn, объявленного выше.

Это возможность, предоставляемая расширением Field to Input, которое позволяет использовать вывод одного поля в качестве входных данных для другого поля. Именно так можно создавать функциональность внутри GraphQL query.

В query поле isNotSubscriberOptInNAValue проверяет, что значение ранее запрошенного поля subscriberOptIn не равно "NA", а subscribedToNewsletter вычисляет операцию AND, включающую значения полей hasSubscriberOptIn и isNotSubscriberOptInNAValue.

​

Подключение к Mailchimp

Операция MaybeCreateContactOnMailchimp содержит логику для извлечения данных из payload и вызова API Mailchimp для добавления email в список рассылки.

Вот операция с комментариями, объясняющими, что делает каждая строка:

query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   @include(if: $subscribedToNewsletter)
{
  # Extract form field `email` from the body of the request
  subscriberEmail: _httpRequestStringParam(name: "email")
  
  # Obtain Mailchimp credentials, defined in wp-config.php
  mailchimpUsername: _env(name: "MAILCHIMP_API_CREDENTIALS_USERNAME")
    # Do not print the credentials in the response
    @remove
  mailchimpPassword: _env(name: "MAILCHIMP_API_CREDENTIALS_PASSWORD")
    @remove
  
  # Connect to Mailchimp to add a new member to the list
  mailchimpListMembersJSONObject: _sendJSONObjectItemHTTPRequest(input: {
    url: "https://us7.api.mailchimp.com/3.0/lists/{listCode}/members",
    method: POST,
    options: {
      # Provide credentials to connect to the API
      auth: {
        username: $__mailchimpUsername,
        password: $__mailchimpPassword
      },
      # Provide form data
      json: {
        email_address: $__subscriberEmail,
        status: "subscribed"
      }
    }
  })
}Copy

Рассмотрим возможности, используемые в этом query.

​

Переменные окружения

Нам нужно предоставить наши учётные данные при подключении к API Mailchimp. Однако мы не хотим вводить их напрямую в GraphQL query, так как они могут где-то утечь (например, могут попасть в какой-нибудь лог).

Именно поэтому мы используем глобальное поле _env (предоставляемое расширением PHP Constants and Environment via Schema) для чтения переменной окружения или PHP-константы, вместе с директивой @remove (предоставляемой расширением Field Response Removal), чтобы не выводить учётные данные в ответе.

Теперь мы можем объявить наши учётные данные в wp-config.php:

define( 'MAILCHIMP_API_CREDENTIALS_USERNAME', '{ username }' );
define( 'MAILCHIMP_API_CREDENTIALS_PASSWORD', '{ password }' );Copy

​

Отправка HTTP-запроса в Mailchimp

Последней частью логики является поле _sendJSONObjectItemHTTPRequest, которое отправляет HTTP-запрос к некоторому сервису.

Поскольку мы хотим подключиться к API Mailchimp, поле mailchimpListMembersJSONObject предоставляет данные, необходимые для REST API-эндпоинта Mailchimp, как указано в документации по добавлению участника в список Mailchimp:

• Отправить запрос POST
• Эндпоинт: https://{subdomain}.api.mailchimp.com/3.0/lists/{listCode}/members
• Тело должно включать поля email_address и status

​

Создание вебхука для взаимодействия с любым API

GraphQL query в этой статье пересылает данные из InstaWP в Mailchimp.

Вы можете применить ту же идею для любой нужной вам комбинации: извлекая данные из какого-либо исходного сервиса (любого), адаптируя их и отправляя в какой-либо целевой сервис (любой).

Удачи!