本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 Objective-C 或 Swift 中使用 API Gateway 為 REST API 產生的 iOS 軟體開發套件
<a name="how-to-generate-sdk-ios"></a>

在本教學中，我們會示範如何在 Objective-C 或 Swift 應用程式中，使用 API Gateway 為 REST API 產生的 iOS 軟體開發套件，以呼叫基礎 API。我們會以 [SimpleCalc API](simple-calc-lambda-api.md) 為例，說明下列主題：
+ 如何在 Xcode 專案中安裝所需的 AWS Mobile SDK 元件
+ 如何在呼叫 API 的方法前，先建立 API 用戶端物件
+ 如何透過 API 用戶端物件上對應的開發套件方法呼叫 API 方法
+ 如何使用開發套件的對應模型類別準備方法輸入和剖析其結果

**Topics**
+ [使用產生的 iOS 開發套件 (Objective-C) 呼叫 API](#how-to-use-sdk-ios-objc)
+ [使用產生的 iOS 開發套件 (Swift) 呼叫 API](#how-to-generate-sdk-ios-swift)

## 使用產生的 iOS 開發套件 (Objective-C) 呼叫 API
<a name="how-to-use-sdk-ios-objc"></a>

開始下列程序之前，您必須先在 Objective-C 中完成[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)中的 iOS 步驟，並下載已產生之軟體開發套件的 .zip 檔案。

### 在 Objective-C 專案中安裝由 API Gateway 產生的 AWS 行動 SDK 和 iOS SDK
<a name="use-sdk-ios-objc-install-sdk"></a>

下列程序說明如何安裝開發套件。

**安裝和使用 API Gateway 在 Objective-C 中產生的 iOS 軟體開發套件**

1. 將您稍早下載之 API Gateway 所產生的 .zip 檔案內容解壓縮。使用 [SimpleCalc API](simple-calc-lambda-api.md)，您可能希望將解壓縮的開發套件資料夾重新命名成類似 **sdk\$1objc\$1simple\$1calc**。在這個開發套件資料夾中，有 `README.md` 檔案和 `Podfile` 檔案。`README.md` 檔案包含開發套件的安裝和使用說明。本教學提供這些說明的詳細資訊。安裝利用 [CocoaPods](https://cocoapods.org) 匯入所需的 API Gateway 程式庫和其他相依 AWS 的 Mobile SDK 元件。您必須更新 `Podfile`，將開發套件匯入至您應用程式的 Xcode 專案。未封存的開發套件資料夾也包含 `generated-src` 資料夾，其中包含 API 之已產生開發套件的原始程式碼。

1. 啟動 Xcode 並建立新的 iOS Objective-C 專案。請記下專案的目標。您需要在 `Podfile` 中設定它。

      
![\[在 Xcode 中尋找目標。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png)

1. 若要使用 CocoaPods AWS Mobile SDK for iOS 將 匯入 Xcode 專案，請執行下列動作：

   1. 在終端機視窗中執行下列命令來安裝 CocoaPods：

      ```
      sudo gem install cocoapods
      pod setup
      ```

   1. 將 `Podfile` 檔案從解壓縮開發套件資料夾複製至包含 Xcode 專案檔的相同目錄。將下列區塊：

      ```
      target '<YourXcodeTarget>' do
          pod 'AWSAPIGateway', '~> 2.4.7'
      end
      ```

      使用您專案的目標名稱：

      ```
      target 'app_objc_simple_calc' do
          pod 'AWSAPIGateway', '~> 2.4.7'
      end
      ```

      如果您的 Xcode 專案已包含一個名為 `Podfile` 的檔案，請將下行程式碼新增到此檔案：

      ```
      pod 'AWSAPIGateway', '~> 2.4.7'
      ```

   1. 開啟終端機視窗並執行下列命令：

      ```
      pod install
      ```

      這會安裝 API Gateway 元件和其他相依的 AWS Mobile SDK 元件。

   1. 關閉 Xcode 專案，然後開啟 `.xcworkspace` 檔案重新啟動 Xcode。

   1. 從解壓縮的開發套件 `.h` 目錄將所有的 `.m` 和 `generated-src` 檔案新增到您的 Xcode 專案。

         
![\[.h 和 .m 檔案位於產生的來源中\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png)

   若要透過明確下載 AWS Mobile SDK 或使用 [Carthage](https://github.com/Carthage/Carthage#installing-carthage) 將 AWS Mobile SDK for iOS Objective-C 匯入您的專案，請遵循 *README.md* 檔案中的指示。請務必僅使用其中一個選項來匯入 AWS Mobile SDK。

### 使用 Objective-C 專案中 API Gateway 產生的 iOS 軟體開發套件呼叫 API 方法
<a name="use-sdk-ios-objc-call-sdk"></a>

當您使用兩個模型來處理這些方法的輸入 (`SIMPLE_CALC`) 和輸出 (`Input`)，為這個 [SimpleCalc API](simple-calc-lambda-api.md) 產生字首為 `Result` 的開發套件後，在開發套件中，產生的 API 用戶端類別會變為 `SIMPLE_CALCSimpleCalcClient`，而對應的資料類別則會分別成為 `SIMPLE_CALCInput` 和 `SIMPLE_CALCResult`。API 請求和回應會對應至開發套件方法，如下所示：
+ 下列的 API 請求：

  ```
  GET /?a=...&b=...&op=...
  ```

  會成為下列的開發套件方法：

  ```
  (AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b
  ```

  如果 `AWSTask.result` 模型已新增至方法回應，則 `SIMPLE_CALCResult` 屬性為 `Result` 類型。否則，屬性為 `NSDictionary` 類型。
+ 下列的此 API 請求：

  ```
  POST /
      
  {
     "a": "Number",
     "b": "Number",
     "op": "String"
  }
  ```

  會成為下列的開發套件方法：

  ```
  (AWSTask *)rootPost:(SIMPLE_CALCInput *)body
  ```
+ 下列的 API 請求：

  ```
  GET /{a}/{b}/{op}
  ```

  會成為下列的開發套件方法：

  ```
  (AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op
  ```

下列程序說明如何在 Objective-C 應用程式原始碼中呼叫 API 方法；例如，在 `viewDidLoad` 檔案中作為 `ViewController.m` 委派的一部分。

**透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API**

1. 匯入 API 用戶端類別標頭檔案，以能在應用程式中呼叫 API 用戶端類別：

   ```
   #import "SIMPLE_CALCSimpleCalc.h"
   ```

   `#import` 陳述式也針對兩個模型類別匯入 `SIMPLE_CALCInput.h` 和 `SIMPLE_CALCResult.h`。

1. 將 API 用戶端類別執行個體化：

   ```
   SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient];
   ```

   若要使用 Amazon Cognito 與 API，請先在預設的 `AWSServiceManager` 物件上設定 `defaultServiceConfiguration` 屬性，如下所示，然後呼叫 `defaultClient` 方法以建立 API 用戶端物件 (如前例所示)：

   ```
   AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id];
   AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds];
   AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
   ```

1. 呼叫 `GET /?a=1&b=2&op=+` 方法來執行 `1+2`：

   ```
   [[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
       _textField1.text = [self handleApiResponse:task];
       return nil;
   }];
   ```

   協助程式函數 `handleApiResponse:task` 會在此將結果格式化為字串並顯示在文字欄位中 (`_textField1`)。

   ```
   - (NSString *)handleApiResponse:(AWSTask *)task {
       if (task.error != nil) {
           return [NSString stringWithFormat: @"Error: %@", task.error.description];
       } else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) {
           return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c];
       }
       return nil;
   }
   ```

   產生的顯示畫面為 `1 + 2 = 3`。

1. 呼叫具有承載的 `POST /` 來執行 `1-2`：

   ```
   SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init];
       input.a = [NSNumber numberWithInt:1];
       input.b = [NSNumber numberWithInt:2];
       input.op = @"-";
       [[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
           _textField2.text = [self handleApiResponse:task];
           return nil;
       }];
   ```

   產生的顯示畫面為 `1 - 2 = -1`。

1. 呼叫 `GET /{a}/{b}/{op}` 來執行 `1/2`：

   ```
   [[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
       _textField3.text = [self handleApiResponse:task];
       return nil;
   }];
   ```

   產生的顯示畫面為 `1 div 2 = 0.5`。在此，`div` 用來代替 `/`，因為後端的[簡單 Lambda 函數](simple-calc-nodejs-lambda-function.md)不處理 URL 編碼的路徑變數。

## 使用產生的 iOS 開發套件 (Swift) 呼叫 API
<a name="how-to-generate-sdk-ios-swift"></a>

開始下列程序之前，您必須先在 Swift 中完成[在 API Gateway 中為 REST API 產生 SDK](how-to-generate-sdk.md)中的 iOS 步驟，並下載已產生之軟體開發套件的 .zip 檔案。

**Topics**
+ [在 Swift 專案中安裝 AWS 行動 SDK 和 API Gateway 產生的 SDK](#use-sdk-ios-swift-install-sdk)
+ [在 Swift 專案中透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API 方法](#use-sdk-ios-swift-call-api)

### 在 Swift 專案中安裝 AWS 行動 SDK 和 API Gateway 產生的 SDK
<a name="use-sdk-ios-swift-install-sdk"></a>

下列程序說明如何安裝開發套件。

**安裝和使用 API Gateway 在 Swift 中產生的 iOS 軟體開發套件**

1. 將您稍早下載之 API Gateway 所產生的 .zip 檔案內容解壓縮。使用 [SimpleCalc API](simple-calc-lambda-api.md)，您可能希望將解壓縮的開發套件資料夾重新命名成類似 **sdk\$1swift\$1simple\$1calc**。在這個開發套件資料夾中，有 `README.md` 檔案和 `Podfile` 檔案。`README.md` 檔案包含開發套件的安裝和使用說明。本教學提供這些說明的詳細資訊。安裝會利用 [CocoaPods](https://cocoapods.org) 來匯入所需的 AWS Mobile 開發套件元件。您必須更新 `Podfile`，以將開發套件匯入至您 Swift 應用程式的 Xcode 專案。未封存的開發套件資料夾也包含 `generated-src` 資料夾，其中包含 API 之已產生開發套件的原始程式碼。

1. 啟動 Xcode 並建立新的 iOS Swift 專案。請記下專案的目標。您需要在 `Podfile` 中設定它。

      
![\[在 Xcode 中尋找目標。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png)

1. 若要使用 CocoaPods 將所需的 AWS Mobile SDK 元件匯入 Xcode 專案，請執行下列動作：

   1. 如果未安裝，請在終端機視窗中執行下列命令來安裝 CocoaPods：

      ```
      sudo gem install cocoapods
      pod setup
      ```

   1. 將 `Podfile` 檔案從解壓縮開發套件資料夾複製至包含 Xcode 專案檔的相同目錄。將下列區塊：

      ```
      target '<YourXcodeTarget>' do
          pod 'AWSAPIGateway', '~> 2.4.7'
      end
      ```

      取代為您專案的目標名稱，如下所示：

      ```
      target 'app_swift_simple_calc' do
          pod 'AWSAPIGateway', '~> 2.4.7'
      end
      ```

      如果您的 Xcode 專案已包含具有正確目標的 `Podfile`，您可以只將下列程式碼行新增至 `do ... end` 迴圈：

      ```
      pod 'AWSAPIGateway', '~> 2.4.7'
      ```

   1. 開啟終端機視窗，並在應用程式目錄中執行下列命令：

      ```
      pod install
      ```

      這會將 API Gateway 元件和任何相依的 AWS Mobile SDK 元件安裝到應用程式的專案中。

   1. 關閉 Xcode 專案，然後開啟 `*.xcworkspace` 檔案重新啟動 Xcode。

   1. 將所有開發套件的標頭檔案 (`.h`) 和 Swift 原始程式碼檔案 (`.swift`) 從擷取的 `generated-src` 目錄新增至 Xcode 專案。

         
![\[.h 和 .swift 檔案位於產生的來源中\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png)

   1. 若要啟用從 Swift 程式碼專案呼叫 AWS Mobile SDK 的 Objective-C 程式庫，請在您 Xcode 專案組態的 **Swift 編譯器 - 一般**設定下，在 **Objective-C 橋接標頭**屬性上設定`Bridging_Header.h`檔案路徑：

         
![\[在「Swift 編譯器 - 一般」下，設定 Bridging_Header.h 檔案路徑。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png)
**提示**  
您可以在 Xcode 的搜尋方塊中輸入 **bridging**，以尋找 **Objective-C Bridging Header (Objective-C 橋接標頭)** 屬性。

   1. 建置 Xcode 專案，驗證已正確地設定它，再繼續進行。如果您的 Xcode 使用的 Swift 版本比 AWS Mobile SDK 支援的版本更新，您會收到 Swift 編譯器錯誤。在這種情況下，於 **Swift Compiler - Version (Swift 編譯器 - 版本)** 設定下方，將 **Use Legacy Swift Language Version (使用傳統 Swift 語言版本)** 屬性設定為 **Yes (是)**：

         
![\[將 Legacy Swift 語言版本屬性設定為「是」。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png)

   若要透過明確下載 AWS Mobile SDK 或使用 [Carthage](https://github.com/Carthage/Carthage#installing-carthage) 將適用於 iOS 的 AWS Mobile SDK 匯入您的專案，請遵循 SDK 套件隨附的 `README.md` 檔案中的指示。請務必僅使用其中一個選項來匯入 AWS Mobile SDK。

### 在 Swift 專案中透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API 方法
<a name="use-sdk-ios-swift-call-api"></a>

當您使用兩個模型說明 API 請求和回應的輸入 (`Input`) 和輸出 (`Result`)，為這個 [SimpleCalc API](simple-calc-lambda-api.md) 產生字首為 `SIMPLE_CALC` 的開發套件後，在開發套件中，產生的 API 用戶端類別會變為 `SIMPLE_CALCSimpleCalcClient`，而對應的資料類別則會分別成為 `SIMPLE_CALCInput` 和 `SIMPLE_CALCResult`。API 請求和回應會對應至開發套件方法，如下所示：
+ 下列的 API 請求：

  ```
  GET /?a=...&b=...&op=...
  ```

  會成為下列的開發套件方法：

  ```
  public func rootGet(op: String?, a: String?, b: String?) -> AWSTask
  ```

  如果 `AWSTask.result` 模型已新增至方法回應，則 `SIMPLE_CALCResult` 屬性為 `Result` 類型。否則，它為 `NSDictionary` 類型。
+ 下列的此 API 請求：

  ```
  POST /
      
  {
     "a": "Number",
     "b": "Number",
     "op": "String"
  }
  ```

  會成為下列的開發套件方法：

  ```
  public func rootPost(body: SIMPLE_CALCInput) -> AWSTask
  ```
+ 下列的 API 請求：

  ```
  GET /{a}/{b}/{op}
  ```

  會成為下列的開發套件方法：

  ```
  public func aBOpGet(a: String, b: String, op: String) -> AWSTask
  ```

下列程序說明如何在 Swift 應用程式原始碼中呼叫 API 方法；例如，在 `viewDidLoad()` 檔案中做為 `ViewController.m` 委派的一部分。

**透過 API Gateway 所產生的 iOS 軟體開發套件來呼叫 API**

1. 將 API 用戶端類別執行個體化：

   ```
   let client = SIMPLE_CALCSimpleCalcClient.default()
   ```

   若要搭配 API 使用 Amazon Cognito，請先設定預設 AWS 服務組態 （如下所示），再取得`default`方法 （如先前所示）：

   ```
   let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id")        
   let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider)        
   AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
   ```

1. 呼叫 `GET /?a=1&b=2&op=+` 方法來執行 `1+2`：

   ```
   client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in
       self.showResult(task)
       return nil
   }
   ```

   其中，helper 函數 `self.showResult(task)` 會將結果或錯誤列印至主控台，例如：

   ```
   func showResult(task: AWSTask) {
       if let error = task.error {
           print("Error: \(error)")
       } else if let result = task.result {
           if result is SIMPLE_CALCResult {
               let res = result as! SIMPLE_CALCResult
               print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!))
           } else if result is NSDictionary {
               let res = result as! NSDictionary
               print("NSDictionary: \(res)")
           }
       }
   }
   ```

   在生產應用程式中，您可以在文字欄位中顯示結果或錯誤。產生的顯示畫面為 `1 + 2 = 3`。

1. 呼叫具有承載的 `POST /` 來執行 `1-2`：

   ```
   let body = SIMPLE_CALCInput()
   body.a=1
   body.b=2
   body.op="-"
   client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in
       self.showResult(task)
       return nil
   }
   ```

   產生的顯示畫面為 `1 - 2 = -1`。

1. 呼叫 `GET /{a}/{b}/{op}` 來執行 `1/2`：

   ```
   client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in
       self.showResult(task)
       return nil
   }
   ```

   產生的顯示畫面為 `1 div 2 = 0.5`。在此，`div` 用來代替 `/`，因為後端的[簡單 Lambda 函數](simple-calc-nodejs-lambda-function.md)不處理 URL 編碼的路徑變數。