支援終止通知：2027 年 3 月 31 日， AWS 將終止對 Amazon WorkMail 的支援。2027 年 3 月 31 日之後，您將無法再存取 Amazon WorkMail 主控台或 Amazon WorkMail 資源。如需詳細資訊，請參閱 [Amazon WorkMail 終止支援](https://docs.aws.amazon.com/workmail/latest/adminguide/workmail-end-of-support.html)。

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

# 建置自訂可用性提供者 Lambda 函數
<a name="building_cap"></a>

自訂可用性提供者 (CAPs) 是使用以 JSON 為基礎的請求和回應通訊協定進行設定，該通訊協定是以定義良好的 JSON 結構描述撰寫。Lambda 函數會剖析請求並提供有效的回應。

**Topics**
+ [請求和回應元素](#cap_request_response_elements)
+ [授與 存取權](#granting_access)
+ [使用 CAP Lambda 函數的 Amazon WorkMail 範例](#cap_example_github)

## 請求和回應元素
<a name="cap_request_response_elements"></a>

### 請求元素
<a name="cap_request"></a>

以下是用於為 Amazon WorkMail 使用者設定 CAP 的範例請求：

```
{
    "requester": {
        "email": "user1@internal.example.com",
        "userName": "user1",
        "organization": "m-0123456789abcdef0123456789abcdef",
        "userId": "S-1-5-18",
        "origin": "127.0.0.1"
    },
    "mailboxes": [
        "user2@external.example.com",
        "unknown@internal.example.com"
    ],
    "window": {
        "startDate": "2021-05-04T00:00:00.000Z",
        "endDate": "2021-05-06T00:00:00.000Z"
    }
}
```

請求由三個部分組成：**申請者**、**信箱**和**視窗**。這些會在本指南的下列 [信箱](#cap_request_mailboxes)、 [要求者](#cap_request_requester)和 [視窗](#cap_request_window)章節中說明。

#### 要求者
<a name="cap_request_requester"></a>

*請求者*區段提供向 Amazon WorkMail 提出原始請求之使用者的相關資訊。CAPs會使用此資訊來變更提供者的行為。例如，此資料可用來模擬後端可用性提供者上的相同使用者，或從回應中省略某些詳細資訊。


| 欄位 | Description | 必要 | 
| --- | --- | --- | 
|  `Email`  |  申請者的主要電子郵件地址。  |  是  | 
|  `Username`  |  請求者的使用者名稱。  |  是  | 
|  `Organization`  |  申請者的組織 ID。  |  是  | 
|  `UserID`  |  請求者 ID。  |  是  | 
|  `Origin`  |  請求的遠端地址。  |  否  | 
|  `Bearer`  |  保留以供日後使用。  |  否  | 

#### 信箱
<a name="cap_request_mailboxes"></a>

*信箱*區段包含要求可用性資訊之使用者電子郵件地址的逗號分隔清單。

#### 視窗
<a name="cap_request_window"></a>

*視窗*區段包含請求可用性資訊的時段。`startDate` 和 均以 UTC `endDate`指定，並根據 [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) 格式化。事件預計不會被截斷。換句話說，如果事件在定義的 之前啟動`StartDate`，則會使用原始啟動。

### 回應元素
<a name="cap_response"></a>

Amazon WorkMail 會等待 25 秒，從 CAP Lambda 函數取得回應。25 秒後，Amazon WorkMail 會假設函數失敗，並在 EWS GetUserAvailability 回應中為相關聯的信箱產生失敗。這不會導致整個 GetUserAvailability 操作失敗。

以下是本節開頭所定義組態的範例回應：

```
{
    "mailboxes": [{
        "mailbox": "user2@external.example.com",
        "events": [{
            "startTime": "2021-05-03T23:00:00.000Z",
            "endTime": "2021-05-04T03:00:00.000Z",
            "busyType": "BUSY"|"FREE"|"TENTATIVE",
            "details": {  // optional
                "subject": "Late meeting",
                "location": "Chime",
                "instanceType": "SINGLE_INSTANCE"|"RECURRING_INSTANCE"|"EXCEPTION",
                "isMeeting": true,
                "isReminderSet": true,
                "isPrivate": false
            }
        }],
        "workingHours": {
            "timezone": {
                "name": "W. Europe Standard Time"
                "bias": 60,
                "standardTime": {  // optional (not needed for fixed offsets)
                    "offset": 60,
                    "time": "02:00:00",
                    "month": "JAN"|"FEB"|"MAR"|"APR"|"JUN"|"JUL"|"AUG"|"SEP"|"OCT"|"NOV"|"DEC",
                    "week": "FIRST"|"SECOND"|"THIRD"|"FOURTH"|"LAST",
                    "dayOfWeek": "SUN"|"MON"|"TUE"|"WED"|"THU"|"FRI"|"SAT"
                },
                "daylightTime": {  // optional (not needed for fixed offsets)
                    "offset": 0,
                    "time": "03:00:00",
                    "month": "JAN"|"FEB"|"MAR"|"APR"|"JUN"|"JUL"|"AUG"|"SEP"|"OCT"|"NOV"|"DEC",
                    "week": "FIRST"|"SECOND"|"THIRD"|"FOURTH"|"LAST",
                    "dayOfWeek": "SUN"|"MON"|"TUE"|"WED"|"THU"|"FRI"|"SAT"
                },                
            },
            "workingPeriods":[{
                "startMinutes": 480,
                "endMinutes": 1040,
                "days": ["SUN"|"MON"|"TUE"|"WED"|"THU"|"FRI"|"SAT"]
            }]
        }
    },{
        "mailbox": "unknown@internal.example.com",
        "error": "MailboxNotFound"
    }]
}
```

回應由包含*信箱*清單的單一信箱區段組成。成功取得可用性的每個信箱都由三個部分組成：*信箱*、*事件*和*工作時間*。如果可用性提供者無法取得信箱的可用性資訊，則區段由兩個區段組成：*信箱*和*錯誤*。這些會在本指南的下列 [信箱](#cap_response_mailbox)、[事件](#cap_response_events)、[工作期間](#cap_response_workingperiods)、、 [工作時間](#cap_response_workinghours) [時區](#cap_response_timezone)和 [錯誤](#cap_response_error)章節中說明。

#### 信箱
<a name="cap_response_mailbox"></a>

*信箱*區段是在請求的*信箱*區段中找到的使用者電子郵件地址。

#### 事件
<a name="cap_response_events"></a>

*事件*區段是在請求視窗中發生的事件清單。每個事件都以下列參數定義：


| 欄位 | Description | 必要 | 
| --- | --- | --- | 
|  `startTime`  |  事件的開始時間，以 UTC 顯示，並根據 [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) 格式化。  |  是  | 
|  `endTime`  |  事件的結束時間，以 UTC 顯示，並根據 [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) 格式化。  |  是  | 
|  `busyType`  |  事件的忙碌類型。可以是 `Busy`、`Free` 或 `Tentative`。  |  是  | 
|  `details`  |  事件的詳細資訊。  |  否  | 
|  `details.subject`  |  事件的主旨。  |  是  | 
|  `details.location`  |  事件的位置。  |  是  | 
|  `details.instanceType`  |  事件的執行個體類型。可以是 `Single_Instance`、`Recurring_Instance` 或 `Exception`。  |  是  | 
|  `details.isMeeting`  |  指出事件是否有出席者的布林值。  |  是  | 
|  `details.isReminderSet`  |  指出事件是否具有提醒集的布林值。  |  是  | 
|  `details.isPrivate`  |  指出事件是否設為私有的布林值。  |  是  | 

#### 工作時間
<a name="cap_response_workinghours"></a>

*workingHours* 區段包含信箱擁有者工作時間的相關資訊。它包含兩個區段：*時區*和*workingPeriods*。

#### 時區
<a name="cap_response_timezone"></a>

*時區*子區段說明信箱擁有者的時區。當請求者在不同時區運作時，正確轉譯使用者的工作時間非常重要。可用性提供者需要明確描述時區，而不是使用名稱。使用獨立的時區描述有助於避免時區不相符。


| 欄位 | Description | 必要 | 
| --- | --- | --- | 
|  `name`  |  時區的名稱。  |  是  | 
|  `bias`  |  預設與 GMT 的偏移，以分鐘為單位。  |  是  | 
|  `standardTime`  |  指定時區的標準時間開始時間。  |  否  | 
|  `daylightTime`  |  指定時區的日光節約時間開始時間。  |  否  | 

您必須同時定義 `standardTime`和 `daylightTime`，或省略兩者。`standardTime` 和 `daylightTime` 物件中的欄位為：


| 欄位 | Description | 允許值 | 
| --- | --- | --- | 
|  `offset`  |  相對於預設位移的位移，以分鐘為單位。  |  NA  | 
|  `time`  |  標準時間與日光節約時間之間發生轉換的時間，指定為 `hh:mm:ss`。  |  NA  | 
|  `month`  |  標準時間與日光節約時間之間發生轉換的月份。  |  `JAN`,`FEB`, `MAR`, `APR`, `JUN`, `JUL`, `AUG`, `SEP`, `OCT`, `NOV`, `DEC`  | 
|  `week`  |  在指定月份內的一週，即標準時間和日光節約時間之間的轉換發生。  |  `FIRST`, `SECOND`, `THIRD`, `FOURTH`, `LAST`  | 
|  `dayOfWeek`  |  標準時間與日光節約時間之間發生轉換的指定週內日期。  |  `SUN`, `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`  | 

#### 工作期間
<a name="cap_response_workingperiods"></a>

*workingPeriods* 區段包含一或多個工作期間物件。每個期間都會定義一天或多天的開始和結束工作日。


| 欄位 | Description | 允許值 | 
| --- | --- | --- | 
|  `startMinutes`  |  工作日的開始，從午夜起以分鐘為單位。  |  NA  | 
|  `endMinutes`  |  工作日結束，從午夜開始以分鐘為單位。  |  NA  | 
|  `days`  |  此期間適用的天數。  |  `SUN`, `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`  | 

#### 錯誤
<a name="cap_response_error"></a>

*錯誤*欄位可以包含任意錯誤訊息。下表列出已知代碼與 EWS 錯誤代碼的映射。所有其他訊息都會映射至 `ERROR_FREE_BUSY_GENERATION_FAILED`。


| Value | EWS 錯誤代碼 | 
| --- | --- | 
|  `MailboxNotFound`  |  `ERROR_MAIL_RECIPIENT_NOT_FOUND`  | 
|  `ErrorAvailabilityConfigNotFound`  |  `ERROR_AVAILABILITY_CONFIG_NOT_FOUND`  | 
|  `ErrorServerBusy`  |  `ERROR_SERVER_BUSY`  | 
|  `ErrorTimeoutExpired`  |  `ERROR_TIMEOUT_EXPIRED`  | 
|  `ErrorFreeBusyGenerationFailed`  |  `ERROR_FREE_BUSY_GENERATION_FAILED`  | 
|  `ErrorResponseSchemaValidation`  |  `ERROR_RESPONSE_SCHEMA_VALIDATION`  | 

## 授與 存取權
<a name="granting_access"></a>

從 AWS Command Line Interface () 執行下列 Lambda 命令AWS CLI。此命令會將資源政策新增至剖析 CAP 的 Lambda 函數。此函數允許 Amazon WorkMail 可用性服務調用您的 Lambda 函數。

```
aws lambda add-permission \
    --region LAMBDA_REGION \
    --function-name CAP_FUNCTION_NAME \
    --statement-id AllowWorkMail \
    --action "lambda:InvokeFunction" \
    --principal availability.workmail.WM_REGION.amazonaws.com \
    --source-account WM_ACCOUNT_ID \
    --source-arn arn:aws:workmail:WM_REGION:WM_ACCOUNT_ID:organization/ORGANIZATION_ID
```

在 命令中，依指示新增下列參數：
+ *LAMBDA\$1REGION* — 部署 CAP Lambda 的區域名稱。例如 `us-east-1`。
+ *CAP\$1FUNCTION\$1NAME* — CAP Lambda 函數的名稱。
**注意**  
這可以是 CAP Lambda 函數的名稱、別名或部分或完整 ARN。
+ *WM\$1REGION* — Amazon WorkMail 組織調用 Lambda 函數的區域名稱。
**注意**  
只有下列區域可用於 CAP：  
美國東部 (維吉尼亞北部)
美國西部 (奧勒岡)
歐洲 (愛爾蘭)
+ *WM\$1ACCOUNT\$1ID* — Organization 帳戶的 ID。
+ *ORGANIZATION\$1ID* — 叫用 CAP Lambda 的組織 ID。例如，組織 ID：m-934ebb9eb57145d0a6cab566ca81a21f。

**注意**  
只有在需要跨區域呼叫時，*LAMBDA\$1REGION* 和 *WM\$1REGION* 才會不同。如果不需要跨區域呼叫，它們將是相同的。

## 使用 CAP Lambda 函數的 Amazon WorkMail 範例
<a name="cap_example_github"></a>

如需使用 CAP Lambda 函數查詢 EWS 端點的 Amazon WorkMail 範例，請參閱 Amazon WorkMail GitHub 儲存庫的 Serverless 應用程式上的此[AWS 範例](https://github.com/aws-samples/amazon-workmail-lambda-templates/tree/master/workmail-cap-exchange)應用程式。 * Amazon WorkMail GitHub *