Використання GraphQL API

Пошук операції

Схема є авторитетним джерелом для підтримуваної підмножини GraphQL: кореневих типів операцій, назв, аргументів, вхідних типів і значень enum. Описи містять поради щодо використання, а GraphQL Explorer показує і те, і інше. Для можливостей, доступних лише в REST, використовуйте довідник REST API. Назви операцій відповідають REST-ендпоінтам, до яких вони звертаються, у форматі camelCase. GET /history — це postHistory, GET /analytics/social — це socialAnalytics, POST /post — це createPost.

Queries читають, mutations записують

Queries — це читання та перевірки, які нічого не змінюють на нашому боці. Mutations публікують або змінюють стан, запускають роботу чи надсилають email. Кореневий тип не визначається ні HTTP-методом REST, ні вартістю виклику:

validatePost перевіряє допис, не публікуючи його.
validateMedia перевіряє, чи доступний URL медіа.
generatePost — це query, тому що на нашому боці нічого не змінюється. Проте він усе одно рахується як виклик API і щоразу повертає інший текст, тож переконайтеся, що клієнтський кеш або автоматичне повторне отримання даних не повторює його непомітно для вас.
mediaUploadUrl — це mutation, тому що він створює URL завантаження для вашого акаунта.
linkAnalytics — це mutation, тому що він може запитати звіт електронною поштою.
userBatch — це mutation, тому що він запускає завдання експорту.

Використовуйте Explorer або схему, щоб перевірити кореневий тип кожної підтримуваної операції.

Створення допису

createPost приймає єдиний аргумент input, тож увесь допис — це один об’єкт:

mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}

Вхідні дані повторюють задокументований REST-ендпоінт post, включно з об’єктами опцій для окремих соцмереж і REST-формами, які приймають більше однієї структури JSON:

mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}

Допис може бути успішно опублікований в одній соцмережі й завершитися помилкою в іншій. Це не є збоєм запиту — див. Помилки.

Типи аргументів

Більшість аргументів — звичайні рядки, числа та булеві значення. Варто знати про три випадки.

Enum-и

Багато рядкових аргументів із закритим набором підтримуваних значень є GraphQL enum-ами, які записуються без лапок і великими літерами:

{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }

А не "instagram". Сервер зіставляє кожне прийняте значення enum із точним значенням, яке очікує базовий REST-контролер, — часто, але не завжди, це рядок у нижньому регістрі. Некоректне значення enum відхиляється під час валідації GraphQL ще до виконання операції, тож помилка в написанні вам нічого не коштує. Деякі аргументи мають однакову назву в різних операціях, але приймають різні значення, бо ендпоінти справді відрізняються. reviews(platform:) приймає лише GMB і FACEBOOK, оскільки лише ці соцмережі мають відгуки. Автодоповнення вашого клієнта покаже правильний набір для кожної операції.

Скаляр JSON

Кілька аргументів мають тип JSON, а не конкретний тип. Так буває, коли значення цілком законно може мати кілька структур і жоден окремий тип GraphQL не міг би чесно його описати:

explainError(code:) приймає 215 або “215”, тому що клієнти зберігають коди помилок в обох формах.
createPost(input:) використовує JSON для таких полів, як post і mediaUrls, які можуть бути спільними значеннями або об’єктами для окремих платформ.
createAutomation(triggers:, actions:) приймають масиви, поля яких залежать від type кожного елемента.
boostFacebookPost(interests:) приймає id інтересів Meta як рядки або числа.

Передавайте те саме значення, яке ви надіслали б у тілі відповідного REST-запиту. Аргумент JSON не є лазівкою: резолвер валідує його перед відправленням, тому некоректне значення повертає помилку валідації й не витрачає виклик API.

Необов’язкові аргументи та null

Для необов’язкових аргументів і необов’язкових полів усередині вхідних об’єктів явне null нормалізується до пропуску. Елементи null усередині списків зберігаються, якщо тип списку їх допускає.

Читання відповідей

Більшість операцій повертають скаляр JSON, що містить повну REST-обгортку відповіді, тому вибирайте кореневе поле без підполів. createPost наразі повертає типізований PostResult, тож вибирайте його поля:

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}

Типізовані типи відповідей, як-от PostResult, також містять raw: JSON! з повною незміненою REST-відповіддю:

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}

raw — постійне поле, і воно існує для того, щоб нове поле, яке з’являється в REST-відповіді, ніколи не було недоступним із GraphQL, поки ми додаємо для нього типізацію. Якщо вам потрібне щось, чого не надають типізовані поля, запитуйте raw.

Завантаження медіа

Байти медіа не можуть передаватися через GraphQL-запит. GraphQL-запит — це єдиний JSON-документ з лімітом 64 KB, тому немає поля, яке приймало б файл, а кодування зображення в base64 усередині запиту перевищило б цей ліміт для всього, що більше за мініатюру. Підтримуваний спосіб повністю уникає цієї проблеми і в будь-якому разі швидший, ніж завантаження через API, тому що ваші байти потрапляють безпосередньо в сховище:

Запитайте URL завантаження:

mutation { mediaUploadUrl(contentType: "image/jpeg") }

Прочитайте data.mediaUploadUrl.uploadUrl, accessUrl і contentType з поверненого JSON.
Надішліть файл через PUT безпосередньо на uploadUrl, а не до Ayrshare API, встановивши заголовок запиту Content-Type у повернене значення contentType.

Після успішного завантаження передайте accessUrl у createPost.input.mediaUrls:

mutation {
  createPost(input: {
    post: "With a photo"
    platforms: [INSTAGRAM]
    mediaUrls: ["https://the-returned-access-url"]
    idempotencyKey: "instagram-photo-001"
  }) {
    status
    postIds { platform postUrl }
  }
}

Розглядайте uploadUrl як короткочасні облікові дані для запису і не записуйте його в логи та не розкривайте. accessUrl — це URL медіа, який використовується під час створення допису. Ви також можете й надалі використовувати REST-ендпоінти завантаження і посилатися на отримані URL з GraphQL. Обидва інтерфейси використовують ту саму медіатеку.

Що читати далі

Помилки — коди HTTP-статусів, структура помилок і частковий успіх.
Ліміти та білінг — обмеження розміру запитів і як рахуються запити.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Використання GraphQL API

Пошук операції

Queries читають, mutations записують

Створення допису

Типи аргументів

Enum-и

Скаляр JSON

Необов’язкові аргументи та null

Читання відповідей

Завантаження медіа

Що читати далі

​Пошук операції

​Queries читають, mutations записують

​Створення допису

​Типи аргументів

​Enum-и

​Скаляр JSON

​Необов’язкові аргументи та null

​Читання відповідей

​Завантаження медіа

​Що читати далі

Пошук операції

Queries читають, mutations записують

Створення допису

Типи аргументів

Enum-и

Скаляр JSON

Необов’язкові аргументи та null

Читання відповідей

Завантаження медіа

Що читати далі