SOAP API

SOAP API (Simple Object Access Protocol) предоставляет стандартизированный способ общения между системами, обычно используя XML в качестве формата сообщения и работая по протоколам, таким как HTTP, SMTP и другим.

В отличие от REST API, которые используют гибкую модель запроса/ответа и обычно обмениваются данными в формате JSON, SOAP API построены вокруг формального контракта, определенного в WSDL. Этот контракт гарантирует строгое соблюдение стандартов общения, делая SOAP API более жесткими, но также надежными и безопасными - идеальными для предприятий, требующих транзакционной целостности и гарантированной доставки сообщения.

SOAP API особенно подходят для сценариев, где требуется надежная безопасность и детальная обработка ошибок, таких как в финансовых услугах или телекоммуникациях.

Различие между SOAP API и REST API:

Протокол и формат сообщения: SOAP основан на протоколе с обменом XML-сообщениями, в то время как REST более гибкий, использует методы HTTP и поддерживает несколько форматов данных, таких как JSON и XML.

Жизненный цикл соединения: SOAP работает с независимыми запросами и ответами, в то время как REST является состояние-не-запоминающим, где каждый запрос независим, делая REST более масштабируемым и проще в управлении.

Практическое применение: SOAP предпочтителен в сценариях, где требуются формальные контракты и высокая безопасность, в то время как REST более подходит для легковесных, масштабируемых веб-сервисов.

Пример ответа SOAP
Пример ответа REST

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <GetMatchScoreResponse xmlns="http://example.com/scores">
      <MatchScore>
        <Team1>Red Dragons</Team1>
        <Team2>Silver Sharks</Team2>
        <Score>2-1</Score>
      </MatchScore>
    </GetMatchScoreResponse>
  </soap:Body>
</soap:Envelope>

{
  "event": "match_score",
  "data": {
    "team1": "Red Dragons",
    "team2": "Silver Sharks",
    "score": "2-1"
  }
}

Создание приложения

Это руководство предоставляет пошаговые инструкции о том, как добавить и использовать SOAP API для создания примерного приложения, отображающего список стран. При нажатии на название страны пользователь переходит на страницу с подробностями, где отображается флаг страны. Следуя этим инструкциям, вы сможете узнать, как добавить SOAP API в свое приложение и создать основной поток навигации.

Конечное приложение выглядит так:

Что вы узнаете

Как создавать SOAP API.
Создание API с динамическими данными в теле запроса.
Разбор XML-ответа.
Как осуществлять навигацию и передавать данные на новую страницу.

Чтобы создать подобное приложение, вам понадобятся следующие страницы.

Главная страница: Показывает список всех стран.
Сведения о стране: Показывает флаг страны.

Вот как будет осуществляться навигация между этими страницами:

Поток навигации

Шаги построения приложения следующие:

1. Создание интерфейса

Давайте начнем с создания интерфейса для обеих страниц.

1.1 Главная страница

На этой странице вы отображаете список всех стран, используя виджеты ListView и ListTile.

Главная страница

1.2 Страница с подробностями о стране

На этой странице отображается флаг страны с помощью виджета Image.

Страница с подробностями о стране

2. Создание API

Для создания этого примера мы будем использовать два API из Публичных SOAP API Postman. Вот они:

Прежде чем что-либо строить, связанное с API в вашем приложении, убедитесь, что создали и протестировали API, чтобы убедиться, что все API работают правильно. Итак, давайте создадим и протестируем эти API в нашем проекте.

2.1 getCountries

Этот API извлекает список всех имен и кодов стран. Вы можете добавить этот API, следуя инструкциям здесь.

к сведению

Важно отметить, что для отправки правильного Header в ваши запросы необходимо включить "Content-Type: text/xml; charset=utf-8", и установить тип тела запроса на "Text".

Вот как это сделать:

2.2 getCountryFlag

Этот API дает вам флаг страны на основе ее кода. Вы можете передавать код страны динамически в теле запроса, создав переменную. Посмотрите, как это сделать здесь.

Тело запроса
Шапка

Тело запроса

3. Создание пользовательских действий

API, добавленные на предыдущем шаге, возвращают результат в формате XML, который необходимо разобрать, чтобы извлечь соответствующие данные или информацию. Это можно сделать с помощью пользовательского действия. Пользовательское действие может использовать пакет 'xml' для разбора XML-ответа и извлечения данных в формате, легко отображаемом на виджетах пользовательского интерфейса.

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

3.1 parseListofCountries

Это пользовательское действие разбирает результат API getCountries и выдает список стран в переменной List с Type String.

Вот код с комментариями:

// Автоматические импорты FlutterFlow
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Импортировать другие пользовательские действия
import '/flutter_flow/custom_functions.dart'; // Импортировать пользовательские функции
import 'package:flutter/material.dart';
// Начало кода пользовательского действия
// НЕ УДАЛЯТЬ ИЛИ ИЗМЕНЯТЬ КОД ВЫШЕ!

import 'package:xml/xml.dart';

Future<List<String>> parseListofCountries(String xmlResponse) async {
  final document = XmlDocument.parse(xmlResponse);
  final countryList = <String>[]; // Создать пустой список для хранения стран

  // Найти все элементы с тегом 'm:tCountryCodeAndName'
  final countryElements = document.findAllElements('m:tCountryCodeAndName');
  // Пройтись по всем найденным элементам 'm:tCountryCodeAndName'
  for (final countryElement in countryElements) {
    // Извлечь код страны из элемента
    final countryCode = countryElement.findElements('m:sISOCode').single.text;
    // Извлечь название страны из элемента
    final countryName = countryElement.findElements('m:sName').single.text;
    // Добавить код и название страны в список стран как одну строку
    countryList.add('$countryCode - $countryName');
  }

  print(countryList);
  return countryList;
}

Вот как это выглядит после добавления:

Пользовательское действие для разбора списка стран

3.2 parseCountryDetails

Это пользовательское действие разбирает результат API getCountryFlag. Оно использует цепочку методов для навигации к нужному элементу и извлечения URL флага.

Вот код с комментариями:

// Автоматические импорты FlutterFlow
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Импортировать другие пользовательские действия
import '/flutter_flow/custom_functions.dart'; // Импортировать пользовательские функции
import 'package:flutter/material.dart';
// Начало кода пользовательского действия
// НЕ УДАЛЯТЬ ИЛИ ИЗМЕНЯТЬ КОД ВЫШЕ!

import 'package:xml/xml.dart';

Future<String> parseCountryDetails(String xmlResponse) async {
  final document = XmlDocument.parse(xmlResponse);

  return document
      .getElement('soap:Envelope')! // Получить элемент soap:Envelope
      .getElement('soap:Body')! // Получить элемент soap:Body
      .getElement('m:CountryFlagResponse')! // Получить элемент m:CountryFlagResponse
      .getElement('m:CountryFlagResult')! // Получить элемент m:CountryFlagResult
      .text // Получить текстовое значение элемента
      .trim(); // Удалить начальные или конечные пробелы
}

Вот как это выглядит после добавления:

4. Отображение списка стран

Теперь можно приступить к отображению списка стран на Главной странице. Вот шаги, которые следует выполнить:

Откройте Главную страницу.
Создайте переменную состояния страницы (например, countries), чтобы хранить список стран. Она будет использоваться для связывания данных в ListView.
Выберите страницу и добавьте следующую цепочку действий.
1. Вызов API getCountries.
2. По успеху добавьте пользовательское действие для parseListOfCountries. Важно отметить, что необходимо передать результат предыдущего вызова API в качестве аргумента функции и установить API Response Options на Raw Body Text. Также укажите Имя переменной для вывода действия.
3. Добавьте действие обновления состояния страницы и задайте значение переменной (например, countries) равным выводу пользовательского действия (ранее добавленному). Убедитесь, что Тип обновления установлен на Rebuild Current Page.

4. В ListView генерация динамических элементов с использованием переменной состояния страницы.

Переменная состояния страницы хранит название и код страны в виде одной строки (например, Австралия - AU). Чтобы отобразить название и код отдельно в ListTile, можно использовать выражение кода. Для отображения названия страны используйте var1.split("-")[1].trim(), где var1 — текущий элемент списка. Для отображения кода страны используйте то же выражение, заменив [1] на [0].

5. Навигация на страницу с деталями страны

При нажатии на название страны (ListView > ListTile widget) вы перейдете на страницу CountryDetails и передадите код страны. Этот код будет использоваться для получения флага страны на следующем шаге.

Чтобы это сделать:

Выберите виджет ListTile и добавьте действие для навигации на страницу CountryDetails.
В этом действии нажмите кнопку Define. Откроется страница CountryDetails, где вы сможете определить параметр, который будет принимать код страны.
После определения параметра откройте это действие снова и передайте код страны, используя выражение кода, которое мы использовали на предыдущем шаге (например, var1.split("-")[0].trim()).

Параметр на странице CountryDetails
Передача кода страны при навигации на страницу CountryDetails

Параметр на странице CountryDetails

6. Отображение флага страны

Когда эта страница откроется, она будет содержать код страны (как параметр страницы). Вы можете использовать его для выполнения API-запроса и получения соответствующего флага страны.

Вот пошаговые инструкции:

Откройте страницу CountryPage.
Создайте переменную состояния страницы с Типом ImagePath (например, flagURL) для хранения URL флага. Это значение будет использоваться в виджете Image.
Выберите страницу и добавьте следующую цепочку действий.
1. Вызов API для getCountryFlag.
2. При успешном ответе добавьте пользовательское действие для parseCountryDetails. Важно отметить, что необходимо передать результат предыдущего API-запроса как аргумент функции и установить API Response Options на Raw Body Text. Также добавьте Action Output Variable Name.
3. Добавьте действие обновления состояния страницы и установите переменную (например, flagURL) значением, полученным из пользовательского действия, добавленного ранее. Убедитесь, что тип обновления (Update Type) установлен на Rebuild Current Page.

Теперь просто используйте переменную состояния страницы, чтобы отобразить URL флага в виджете Image.

Получить пример приложения

Получите клонируемую версию этого приложения здесь.

SOAP API

Различие между SOAP API и REST API:​

Создание приложения​

1. Создание интерфейса​

1.1 Главная страница​

1.2 Страница с подробностями о стране​

2. Создание API​

2.1 getCountries​

2.2 getCountryFlag​

3. Создание пользовательских действий​

3.1 parseListofCountries​

3.2 parseCountryDetails​

4. Отображение списка стран​

4. В ListView генерация динамических элементов с использованием переменной состояния страницы.​

5. Навигация на страницу с деталями страны​

6. Отображение флага страны​

Получить пример приложения​