⚠️AWS AppSync SDK for iOS 处于维护模式

有关更多信息，包括如何升级到使用 AWS Amplify API 类别，请参阅 AWS Amplify > API (GraphQL) > 从 AppSync SDK 升级指南

建议：使用 Amplify 客户端连接到 AppSync

对于前端 Web 和移动开发，我们建议使用 Amplify 客户端，这些客户端经过优化以连接到 AppSync 后端。

对于 DynamoDB 数据源，请使用 Amplify 客户端中的 DataStore 类别。它提供最佳的开发者体验以及内置的冲突检测和解决。
对于没有离线要求的场景中的非 DynamoDB 数据源，请使用 Amplify 客户端中的 API (GraphQL) 类别。

AWS AppSync SDK for iOS

AWS AppSync SDK for iOS 使您能够访问 AWS AppSync 后端并执行诸如 Queries、Mutations 和 Subscriptions 等操作。该 SDK 还包括对离线操作的支持。此 SDK 基于这里提供的 Apollo 项目。请在这个 repo 中记录关于此客户端 SDK 的问题，并在官方 AWS AppSync 论坛中记录关于 AppSync 服务的问题。

设置

注意：AWS AppSync 使用 Swift 5.1。使用 Xcode 11.0 或更高版本进行构建。

安装 SDK

通过 Swift Package Manager

Swift Package Manager 与 Xcode 一起分发。要开始将 AWS SDK 添加到您的 iOS 项目，请在 Xcode 中打开您的项目并选择 **File > Swift Packages > Add Package Dependency**。
将 AWS AppSync SDK for iOS GitHub 存储库的 URL (https://github.com/awslabs/aws-mobile-appsync-sdk-ios) 输入到搜索栏中，然后单击 **Next**。
您将看到存储库规则，用于指定希望 Swift Package Manager 安装的 SDK 版本。选择第一个规则 **Version**，然后选择 **Up to Next Major**，因为它将使用可以从 main 分支检测到的最新兼容版本依赖项，然后单击 **Next**。
选择 **AWSAppSync** 包产品并单击 **Finish**。
在您的源文件中，使用 import AWSAppSync 导入 SDK。

通过 CocoaPods

将以下行添加到您的 Podfile

pod 'AWSAppSync', '~> 3.7.1'

示例

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'

target 'EventsApp' do
  # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
  use_frameworks!

  # Pods for EventsApp
  pod 'AWSAppSync', '~> 3.7.1'
end

运行 pod install 安装 AppSync SDK，然后在 Xcode 中打开 **.xcworkspace** 文件（而不是 .xcodeproj 文件）。
现在 **Build** 您的项目以开始使用 SDK。每当发布新版本的 SDK 时，您可以通过运行 pod update 并重建您的项目来更新并使用新功能。
在您的源文件中，使用 import AWSAppSync 导入 SDK。

通过 Carthage

XCFrameworks (推荐)

Carthage 在 Xcode 12 或更高版本中支持 XCFrameworks。按照以下步骤使用 XCFrameworks 使用适用于 iOS 的 AWS SDK

安装 Carthage 0.37.0 或更高版本。

将以下内容添加到您的 Cartfile

github "awslabs/aws-mobile-appsync-sdk-ios"

然后运行以下命令
```
 $ carthage update --use-xcframeworks
```
在应用程序目标的“常规”设置选项卡中的“嵌入式二进制文件”部分，将要使用的每个 xcframework 从磁盘上的 Carthage/Build 文件夹拖放到该部分。

注意：如果您使用的是 XCFrameworks（即，Carthage 或动态框架），则模块 AWSMobileClient 被命名为 AWSMobileClientXCF，以解决 Swift 问题。要使用 AWSMobileClient，请将其导入为

    import AWSMobileClientXCF

并在您的应用程序代码中使用它，而无需 XCF 后缀。

    AWSMobileClient.default.initialize()

带有“胖库”的框架（不推荐）

要构建二进制文件中具有多个架构的特定于平台的框架包，（Xcode 11 及更低版本）

将以下内容添加到您的 Cartfile

github "awslabs/aws-mobile-appsync-sdk-ios"

完成后，运行 carthage update 并使用 Xcode 打开 *.xcworkspace 并选择您的 Target。在 General 选项卡中，找到 Embedded Binaries，然后选择 + 按钮。
选择 Add Other 按钮，导航到 Carthage > Build > iOS 下的 AWS<#ServiceName#>.framework 文件，然后选择 AWSAppSync.framework 及其所需的依赖项
- AWSAppSync.framework
- AWSCore.framework
- Reachability.framework
- SQLite.framework
- AppSyncRealTimeClient.framework
- Starscream.framework
如果出现提示，请勿选中 Destination: Copy items（如果需要）复选框。
在 Target 的 Build Phases 选项卡下，选择左上角的 + 按钮，然后选择 New Run Script Phase。如下设置构建阶段。确保此阶段位于 Embed Frameworks 阶段之下。
```
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/AWSCore.framework/strip-frameworks.sh"
```
选项
- **Shell**: /bin/sh
- **Show environment variables in build log**: 已选中
- **Run script only when installing**: 未选中
- **Input Files**: 空
- **Output Files**: 空
现在 **Build** 您的项目以开始使用 SDK。每当发布新版本的 SDK 时，您可以通过运行 carthage update 并重建您的项目来更新并使用新功能。

注意：目前，AWSAppSync SDK for iOS 使用 Xcode 12.0 构建 Carthage 二进制文件。要使用预构建的二进制文件，您的 Xcode 版本需要相同。否则，您必须通过将 --no-use-binaries 标志传递给 carthage update 命令，在您的机器上构建框架。
在您的源文件中，使用 import AWSAppSync 导入 SDK。

代码生成

要使用 AppSync SDK，您需要使用 AWS Amplify CLI 中的 amplify codegen。此命令将生成与您的架构对应的 Swift 语言文件。您可以直接与这些类交互，而不是直接对 GraphQL 查询文档进行操作。您可以在此处找到使用代码生成的说明。

示例

您可以在此处找到使用 AppSync SDK 的示例应用程序：https://github.com/aws-samples/aws-mobile-appsync-events-starter-ios

文档

您可以在此处找到有关设置代码生成后端并通过 iOS 客户端访问它的分步演练：https://docs.amplify.aws/sdk/api/graphql/q/platform/ios

贡献

贡献指南在此处注明。

测试贡献

如果您要为 SDK 做出贡献，建议添加一些单元和/或集成测试，并针对现有测试进行评估。

调用测试

AWSAppSync 目标配置为在其 Test 配置中运行单元测试和集成测试。按照以下说明完成集成测试设置后，您可以通过在 Xcode 中调用“Product > Test”（⌘-U）来运行这两个套件。

要仅运行一个测试套件（单元或集成），请从 Scheme 选择器中选择相应的目标，然后调用“Product > Test”（⌘-U）。虽然单元测试的运行速度比集成测试快得多，但我们建议在提交 PR 之前运行这两个测试。

设置单元测试

单元测试不需要任何特定的设置，可以直接从您的 Xcode IDE 运行。

注意：目前，任何需要网络活动的测试都放在集成测试中，即使该测试命中 localhost 而不是有效的服务。

设置集成测试

要运行集成测试，您将需要以下内容

两个带有 Posts 架构的 AppSync API 实例。
- 第一个 AppSync 实例应配置为使用支持未经身份验证的身份的 Cognito Identity Pool。
  - Cognito Identity Pool 的 unauth 角色应具有 AppSync Invoke Full Access 权限。
- 第二个实例应配置为使用 API 密钥身份验证。

您可以通过按照以下步骤获取后端设置

使用 API 密钥身份验证创建具有 AppSync API 的堆栈
1. 转到 AWS CloudFormation 控制台。
2. 单击 **Create stack**，然后选择 **Upload a template file**。单击 **Choose File**，然后导航到此项目中的 Cloud Formation Template：AWSAppSyncIntegrationTests/ConsoleResources/appsync-integrationtests-cloudformation.yaml
3. 单击 **Next**
4. 键入“堆栈名称”和“ResourceNamePrefix”
  - 我们建议使用一个“ResourceNamePrefix”，以便于区分堆栈是否用于 AppSync 测试，例如 AppSyncTest<YYYYMMDDHHMM>。
  - 由于您将为这些测试创建两个堆栈，一个使用 API 密钥身份验证，另一个使用 IAM（Cognito Identity）身份验证，因此我们建议选择一个堆栈名称，以便于区分这两个堆栈，例如 AppSyncTest<YYYYMMDDHHMM>-APIKey 和 AppSyncTest<YYYYMMDDHHMM>-IAM。
5. 选择 ApiKey 身份验证类型
6. 堆栈完成后，单击 **Output** 选项卡。
7. 将适当的值复制到测试配置文件 AppSyncIntegrationTests/appsync_test_credentials.json
  - AppSyncApiKey
  - AppSyncEndpointAPIKey
  - AppSyncEndpointAPIKeyRegion
按照上面的步骤 1-6 创建另一个 CloudFormation 堆栈，但在步骤 5 中选择“IAM”身份验证类型。
1. 将适当的值复制到测试配置文件 AppSyncIntegrationTests/appsync_test_credentials.json
  - AppSyncEndpoint
  - AppSyncRegion
  - CognitoIdentityPoolId
  - CognitoIdentityPoolRegion
  - BucketName
  - BucketRegion
  - AppSyncMultiAuthAPIKey
按照上面的步骤 1-6 创建另一个 CloudFormation 堆栈，并将 API Key 作为身份验证类型（我们稍后会更改它）
1. 使用此项目在 AWSAppSyncIntegrationTests/ConsoleResources/appsync-lambda-authorize r.js 提供的模板创建 Lambda 函数
2. 堆栈完成后，单击 **Outputs** 选项卡
3. 将适当的值复制到测试配置文件 AppSyncIntegrationTests/appsync_test_credentials.json
  - AppSyncEndpointAPIKeyLambda
  - AppSyncEndpointAPIKeyLambdaRegion
4. 转到 AWS AppSync 控制台，选择新创建的 AppSync 实例
5. 在 Settings 部分中，将默认身份验证类型更改为 AWS Lambda 并选择在上一步中创建的 Lambda 函数

注意：您必须在 AppSyncIntegrationTests/appsync_test_credentials.json 中或在代码中提供所有值。没有机制来处理一个源的部分覆盖。在运行集成测试之前，必须指定所有值。

选项 1：使用测试配置文件

在 AWSAppSyncIntegrationTests 文件夹中添加文件 appsync_test_credentials.json（请参阅下面的示例），并根据需要替换 AppSyncEndpoint、CognitoIdentityPoolId、AppSyncEndpointAPIKey、AppSyncAPIKey 的值和区域

{
  "AppSyncEndpoint": "https://iambasedendpoint.appsync-api.us-east-1.amazonaws.com/graphql",
  "AppSyncRegion": "us-east-1",
  "CognitoIdentityPoolId": "us-east-1:abcd1234-1234-12324-b4b7-aaa0c0831234",
  "CognitoIdentityPoolRegion": "us-east-1",
  "AppSyncEndpointAPIKey": "https://apikeybasedendpoint.appsync-api.us-east-1.amazonaws.com/graphql",
  "AppSyncEndpointAPIKeyRegion": "us-east-1",
  "AppSyncAPIKey": "da2-sad3lkh23422",
  "BucketName": "bucketName",
  "BucketRegion": "us-east-1",
  "AppSyncMultiAuthAPIKey": "da2-sd34s5ffxz"
}

注意：AppSyncEndpointAPIKey 端点使用基于 API_KEY 的身份验证，而 AppSyncEndpoint 使用基于 AWS_IAM 的身份验证。

选项 2：编辑源代码中的默认值

使用适当的值编辑文件 AWSAppSyncTestCommon/AppSyncClientTestConfigurationDefaults。

现在您应该可以通过在 Xcode 中调用“Product > Test”（⌘-U）来运行集成测试。

许可证

此库已获得 Amazon 软件许可证的许可。