支援終止通知：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會使用此資訊來變更提供者的行為。例如，此資料可用來模擬後端可用性提供者上的相同使用者，或從回應中省略某些詳細資訊。


| 欄位 | 說明 | 必要 | 
| --- | --- | --- | 
| `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>

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


| 欄位 | 說明 | 必要 | 
| --- | --- | --- | 
| `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>

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


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

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


| 欄位 | 說明 | 允許值 | 
| --- | --- | --- | 
| `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* 區段包含一或多個工作期間物件。每個期間都會定義一天或多天的開始和結束工作日。


| 欄位 | 說明 | 允許值 | 
| --- | --- | --- | 
| `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\_REGION}} — 部署 CAP Lambda 的區域名稱。例如 `us-east-1`。
+ {{CAP\_FUNCTION\_NAME}} — CAP Lambda 函數的名稱。
**注意**  
這可以是 CAP Lambda 函數的名稱、別名或部分或完整 ARN。
+ {{WM\_REGION}} — Amazon WorkMail 組織調用 Lambda 函數的區域名稱。
**注意**  
只有下列區域可用於 CAP：  
美國東部 (維吉尼亞北部)
美國西部 (奧勒岡)
歐洲 (愛爾蘭)
+ {{WM\_ACCOUNT\_ID}} — Organization 帳戶的 ID。
+ {{ORGANIZATION\_ID}} — 叫用 CAP Lambda 的組織 ID。例如，組織 ID：m-934ebb9eb57145d0a6cab566ca81a21f。

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

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

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