AWS 合作夥伴中心 API 參考已重組。如需支援的 API 操作的詳細資訊，請參閱 [AWS 合作夥伴中心 API 參考](https://docs.aws.amazon.com/partner-central/latest/APIReference/Welcome.html)。

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

# AWS Partner Central Benefits API 的通知
<a name="benefits-api-events"></a>

Benefits Service 為 BenefitApplications 和 BenefitAllocations 提供 EventBridge 事件。這些事件可讓客戶建置全面的事件驅動型架構，以回應從初始應用程式到配置和最終履行的整個資源生命週期的變更。

**Topics**
+ [完成監控事件的先決條件](#events-prerequites)
+ [設定 Amazon EventBridge 以監控事件](#eventbridge-setup)
+ [進一步了解 優勢 API 事件](#learn-about-events)

## 完成監控事件的先決條件
<a name="events-prerequites"></a>

使用者需要適當的 IAM 許可，才能存取和管理 利益 API 發佈的事件。如需 EventBridge 可用動作、資源和條件索引鍵的詳細資訊，請參閱《[Amazon EventBridge 使用者指南》中的在 Amazon EventBridge 中使用 IAM 政策條件](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-use-conditions.html#events-pattern-detail-type)。 * EventBridge * 其中一個條件索引鍵是 `events:detail-type`，可用於將許可範圍限定為特定事件類型。

下列範例政策示範如何自訂和限制提議事件的許可。`AllowPutRuleForPartnercentralBenefitsEvents` 陳述式允許建立規則，但僅適用於來源的事件`aws.partnercentral-benefits`。

如需詳細的 IAM 政策範例，請參閱 EventBridge 許可上的 AWS 文件。

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowPutRuleForPartnerCentralBenefitsEvents",
      "Effect": "Allow",
      "Action": "events:PutRule",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "events:source": "aws.partnercentral-benefits"
        }
      }
    }
  ]
}
```

## 設定 Amazon EventBridge 以監控事件
<a name="eventbridge-setup"></a>

若要監控效益 API 事件，您可以建立符合您要擷取之事件的 EventBridge 規則。您可以使用AWS Management Console或AWS SDKs來建立和管理規則。以下各節說明如何使用兩種方法建立規則。無論您使用何種方法，都必須在美國東部 （維吉尼亞北部） `us-east-1`區域中建立規則。

### AWS Management Console設定
<a name="eventbridge-console-setup"></a>

若要使用 設定 EventBridge 規則AWS Management Console，請遵循《[Amazon EventBridge 使用者指南》中的建立對 Amazon EventBridge 中的事件做出反應的規則](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html)中的步驟。 * EventBridge * 建立規則時，您必須將事件匯流排設定為**預設值**，並在美國東部 （維吉尼亞北部） `us-east-1`區域中建立規則。

以下是事件規則的範例：

```
{
    "source": ["aws.partnercentral-benefits"],
    "detail": {
        "catalog": ["AWS"]
    }
}
```

### AWS開發套件設定
<a name="eventbridge-sdk-setup"></a>

您可以使用AWS SDKs以程式設計方式建立和管理 EventBridge 規則。如需詳細資訊，請參閱《*Amazon EventBridge API 參考*》中的 [PutRule](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutRule.html)。

下列範例使用適用於 Python 的AWS SDK (Boto3)：

```
import boto3

client = boto3.client('events', region_name='us-east-1')

response = client.put_rule(
    Name='MyBenefitApplicationCreatedRule',
    EventPattern=
    '{
        "source": ["aws.partnercentral-benefits"], 
        "detail-type": ["Benefit Application Created"], 
        "detail": {"catalog": ["AWS"]}
    }',
    State='ENABLED'
)
print('Rule ARN:', response['RuleArn'])
```

## 進一步了解 優勢 API 事件
<a name="learn-about-events"></a>

下列各節說明 API 事件類型的優點、觸發它們的案例，以及事件範例。

### Event types (事件類型)
<a name="types-of-events"></a>

以下是事件類型及其觸發條件。

#### 利益應用程式
<a name="benefit-applications"></a>
+ [已建立利益應用程式](#benefit-application-created)：建立利益應用程式時
+ [利益應用程式審核中](#benefit-application-in-review)：提交利益應用程式時，或應用程式從必要動作轉換回審核中時，會觸發此事件。
+ [需要利益應用程式動作](#benefit-application-action-required)：當內部檢閱者更新應用程式狀態，表示合作夥伴需要提供其他資訊、釐清或修改，才能繼續檢閱時，就會發生此事件。
+ [利益應用程式已拒絕](#benefit-application-rejected)：當內部檢閱者更新應用程式狀態以指出應用程式不符合利益條件或要求，且已拒絕時，就會發生此事件
+ [利益應用程式已核准](#benefit-application-approved)：當內部審核者更新應用程式狀態，表示應用程式已核准利益分配時，就會發生此事件。
+ [利益應用程式階段已變更](#benefit-application-stage-changed)：當內部審核者在業務審核、AWS審核、財務審核等審核程序期間更新應用程式的階段時，就會發生此事件。

#### 利益分配
<a name="benefit-allocations"></a>
+ [利益分配已啟動](#benefit-allocation-activated)：當利益分配由內部服務建立或更新回已啟動時。
+ [利益分配已停用](#benefit-allocation-inactivated)：當內部檢閱者更新配置狀態或利益分配自動過期時，會發生此事件。
+ [利益分配已實現](#benefit-allocation-fulfilled)：當內部檢閱者更新分配狀態以表示配置已完全使用時，就會發生此事件。

### 範例事件
<a name="example-rules"></a>

下列各節提供上一節先前列出的事件範例。

**Topics**
+ [已建立利益應用程式](#benefit-application-created)
+ [利益應用程式審核中](#benefit-application-in-review)
+ [需要利益應用程式動作](#benefit-application-action-required)
+ [利益應用程式遭拒](#benefit-application-rejected)
+ [利益應用程式已核准](#benefit-application-approved)
+ [利益應用程式階段已變更](#benefit-application-stage-changed)
+ [已啟用利益分配](#benefit-allocation-activated)
+ [利益分配已停用](#benefit-allocation-inactivated)
+ [已實現利益分配](#benefit-allocation-fulfilled)

#### 已建立利益應用程式
<a name="benefit-application-created"></a>

##### 觸發內容
<a name="benefit-application-created-context"></a>

當透過 Benefits Service 成功建立新的 Benefit Application 時，Benefit Application Created 事件會發佈到 Amazon EventBridge。當 CreateBenefitApplication API 呼叫成功完成，表示合作夥伴已啟動特定利益的請求時，就會發生此事件。

此事件代表利益應用程式生命週期的開始，並在新應用程式提交至其帳戶時立即通知客戶。

##### 收件人
<a name="benefit-application-created-recipients"></a>

擁有的帳戶會收到利益分配的事件。

##### 範例
<a name="benefit-application-created-example"></a>

```
{
  "id": "7gh88765-k0jh-d08g-i292-2ff1796m030n",
  "detail-type": "Benefit Application Created",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-02-10T15:45:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-application/benappl-12345abcdef123"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitApplication": {
      "id": "benappl-12345abcdef123",
      "fulfillmentTypes": ["CREDITS"],
      "status": "PENDING_SUBMISSION",
      "revision": "hh7e8400-e29b-41d4-a716-446655440012"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 利益應用程式審核中
<a name="benefit-application-in-review"></a>

##### 觸發內容
<a name="benefit-application-in-review-context"></a>

當利益應用程式透過 Benefits Service 轉換為 IN\_REVIEW 狀態時，利益應用程式審核中事件會發佈至 Amazon EventBridge。此事件會在下列情況下發生：
+ 合作夥伴透過 SubmitBenefitApplication API 呼叫提交其應用程式
+ 在合作夥伴解決意見回饋後，應用程式會從 ACTION\_REQUIRED 轉換回 IN\_REVIEW
+ 應用程式會重新叫用，然後重新提交

此事件表示應用程式已進入正式審核程序，且正由AWS內部團隊進行評估。

##### 收件人
<a name="benefit-application-in-review-recipients"></a>

擁有的帳戶會收到利益分配的事件。

##### 範例
<a name="benefit-application-in-review-example"></a>

```
{
  "id": "8hi99876-l1ki-e19h-j303-3gg2807n141o",
  "detail-type": "Benefit Application In Review",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-02-10T16:00:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-application/benappl-12345abcdef123"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitApplication": {
      "id": "benappl-12345abcdef123",
      "fulfillmentTypes": ["CREDITS"],
      "status": "IN_REVIEW",
      "stage": "BUSINESS_REVIEW",
      "revision": "ii8f9511-f30c-52e5-b827-557766551123"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 需要利益應用程式動作
<a name="benefit-application-action-required"></a>

##### 觸發內容
<a name="benefit-application-action-required-context"></a>

當利益應用程式透過 Benefits Service 轉換為 ACTION\_REQUIRED 狀態時，Benefit Application Action Required 事件會發佈至 Amazon EventBridge。當內部檢閱者透過 UpdateBenefitApplicationInternal API 更新應用程式狀態，表示合作夥伴需要提供其他資訊、釐清或修改，才能繼續檢閱時，就會發生此事件。

此事件代表應用程式生命週期中需要合作夥伴介入才能在審核程序中將應用程式向前移動的關鍵點。

##### 收件人
<a name="benefit-application-action-required-recipients"></a>

擁有的帳戶將會收到利益分配的事件

##### 範例
<a name="benefit-application-action-required-example"></a>

```
{
  "id": "9ij00987-m2lj-f20i-k414-4hh3918o252p",
  "detail-type": "Benefit Application Action Required",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-02-12T10:30:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-application/benappl-12345abcdef123"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitApplication": {
      "id": "benappl-12345abcdef123",
      "fulfillmentTypes": ["CREDITS"],
      "status": "ACTION_REQUIRED",
      "stage": "BUSINESS_REVIEW",
      "revision": "jj9g0622-g41d-63f6-c938-668877662234"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 利益應用程式遭拒
<a name="benefit-application-rejected"></a>

##### 觸發內容
<a name="benefit-application-rejected-context"></a>

當 Benefit Application 透過 Benefits Service 轉換為 REJECTED 狀態時，Benefit Application 拒絕事件會發佈至 Amazon EventBridge。當內部檢閱者透過 UpdateBenefitApplicationInternal API 更新應用程式狀態，以指出應用程式不符合利益條件或要求且已遭拒時，就會發生此事件。

此事件代表應用程式生命週期中的結束狀態，其中應用程式已正式拒絕，不會繼續受益配置。

##### 收件人
<a name="benefit-application-rejected-recipients"></a>

擁有的帳戶會收到利益分配的事件。

##### 範例
<a name="benefit-application-rejected-example"></a>

```
{
  "id": "0kl11098-n3mk-g31j-l525-5ii4029p363q",
  "detail-type": "Benefit Application Rejected",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-02-15T14:20:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-application/benappl-12345abcdef123"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitApplication": {
      "id": "benappl-12345abcdef123",
      "fulfillmentTypes": ["CREDITS"],
      "status": "REJECTED",
      "revision": "kk0h1733-h52e-74g7-d049-779988773345"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 利益應用程式已核准
<a name="benefit-application-approved"></a>

##### 觸發內容
<a name="benefit-application-approved-context"></a>

當利益應用程式透過 Benefits Service 轉換為核准狀態時，利益應用程式核准事件會發佈至 Amazon EventBridge。當內部檢閱者透過 UpdateBenefitApplicationInternal API 更新應用程式狀態，表示應用程式符合所有利益條件和要求，並已核准利益分配時，就會發生此事件。

此事件代表應用程式檢閱程序成功完成，通常會觸發對應利益分配的建立。

##### 收件人
<a name="benefit-application-approved-recipients"></a>

擁有的帳戶會收到利益分配的事件。

##### 範例
<a name="benefit-application-approved-example"></a>

```
{
  "id": "1lm22109-o4nl-h42k-m636-6jj5130q474r",
  "detail-type": "Benefit Application Approved",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-02-14T16:45:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-application/benappl-12345abcdef123"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitApplication": {
      "id": "benappl-12345abcdef123",
      "fulfillmentTypes": ["CREDITS"],
      "status": "APPROVED",
      "revision": "ll1i2844-i63f-85h8-e150-880099884456"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 利益應用程式階段已變更
<a name="benefit-application-stage-changed"></a>

##### 觸發內容
<a name="benefit-application-stage-changed-context"></a>

透過 Benefits Service 更新 Benefit Application 的審核階段時，Benefit Application Stage Changed 事件會發佈至 Amazon EventBridge。當內部檢閱者將應用程式的階段更新為其中一個可能的列舉值 (FINANCE\_REVIEW、BUSINESS\_REVIEW、TECH\_REVIEW 和AWS\_REVIEW) 時，就會發生此事件。

與狀態變更不同，階段變更是唯讀資訊更新，可提供內部審核工作流程進展的可見性，而不需要合作夥伴動作。

##### 收件人
<a name="benefit-application-stage-changed-recipients"></a>

擁有的帳戶會收到利益分配的事件。

##### 範例
<a name="benefit-application-stage-changed-example"></a>

```
{
  "id": "2mn33210-p5om-i53l-n747-7kk6241r585s",
  "detail-type": "Benefit Application Stage Changed",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-02-13T11:15:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-application/benappl-12345abcdef123"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitApplication": {
      "id": "benappl-12345abcdef123",
      "fulfillmentTypes": ["CREDITS"],
      "status": "IN_REVIEW",
      "stage": "FINANCIAL_REVIEW",
      "revision": "mm2j3955-j74g-96i9-f261-991100995567"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 已啟用利益分配
<a name="benefit-allocation-activated"></a>

##### 觸發內容
<a name="benefit-allocation-activated-context"></a>

當利益分配透過 利益服務轉換為 ACTIVE 狀態時，利益分配啟用事件會發佈到 Amazon EventBridge。當內部檢閱者透過 UpdateBenefitAllocationInternal API 更新配置狀態，以重新啟用先前非作用中的配置時，就會發生此事件。

當暫時停用的配置 （由於過期、政策變更或管理原因） 還原為作用中狀態時，通常會發生此事件，以便再次獲得合作夥伴使用率的好處。

##### 收件人
<a name="benefit-allocation-activated-recipients"></a>

屬於合作夥伴AWS的帳戶會收到訊息。換言之，擁有資源AWS的帳戶。

##### 範例事件
<a name="benefit-allocation-activated-example"></a>

```
{  
  "id": "3no44321-q6pn-j64m-o858-8ll7352s696t",
  "detail-type": "Benefit Allocation Activated",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-03-01T08:15:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-allocation/benalloc-abc123def456"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitAllocation": {
      "id": "benalloc-abc123def456",
      "fulfillmentType": "CREDITS",
      "status": "ACTIVE"
    },
    "benefitApplication": {
      "id": "benappl-12345abcdef123"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 利益分配已停用
<a name="benefit-allocation-inactivated"></a>

##### 觸發內容
<a name="benefit-allocation-inactivated-context"></a>

當利益分配透過 Benefits Service 轉換為 INACTIVE 狀態時，利益分配停用事件會發佈至 Amazon EventBridge。當內部檢閱者透過 UpdateBenefitAllocationInternal API 更新配置狀態，或當利益分配自動過期時，就會發生此事件。

此事件通常發生在暫停配置時 （由於過期、政策變更、合規問題或管理原因），使得在重新啟用之前無法使用合作夥伴使用利益。

##### 收件人
<a name="benefit-allocation-inactivated-recipients"></a>

屬於合作夥伴AWS的帳戶會收到訊息。換言之，擁有資源AWS的帳戶。

##### 範例事件
<a name="benefit-allocation-inactivated-example"></a>

```
{  
  "id": "4op55432-r7qo-k75n-p969-9mm8463t707u",
  "detail-type": "Benefit Allocation Inactivated",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-06-30T23:59:59Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-allocation/benalloc-abc123def456"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitAllocation": {
      "id": "benalloc-abc123def456",
      "fulfillmentType": "CREDITS",
      "status": "INACTIVE"
    },
    "benefitApplication": {
      "id": "benappl-12345abcdef123"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```

#### 已實現利益分配
<a name="benefit-allocation-fulfilled"></a>

##### 觸發內容
<a name="benefit-allocation-fulfilled-context"></a>

當利益分配透過 Benefits Service 轉換為 FULFILLED 狀態時，利益分配履行事件會發佈到 Amazon EventBridge。當內部檢閱者透過 UpdateBenefitAllocationInternal API 更新配置狀態，表示配置已完全使用，或滿足利益條款時，就會發生此事件。

此事件代表利益生命週期的完成，表示合作夥伴已成功利用配置的利益，或配置已達成自然結論。

##### 收件人
<a name="benefit-allocation-fulfilled-recipients"></a>

屬於合作夥伴AWS的帳戶會收到訊息。換言之，擁有資源AWS的帳戶。

##### 範例事件
<a name="benefit-allocation-fulfilled-example"></a>

```
{  
  "id": "5pq66543-s8rp-l86o-q070-0nn9574u818v",
  "detail-type": "Benefit Allocation Fulfilled",
  "source": "aws.partnercentral-benefits",
  "account": "123456789012",
  "time": "2025-12-15T17:30:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:partnercentral:us-east-1:123456789012:benefit-allocation/benalloc-abc123def456"
  ],
  "detail": {
    "catalog": "AWS",
    "benefitAllocation": {
      "id": "benalloc-abc123def456",
      "fulfillmentType": "CREDITS",
      "status": "FULFILLED"
    },
    "benefitApplication": {
      "id": "benappl-12345abcdef123"
    },
    "benefit": {
      "id": "ben-xyz789uvw012",
      "name": "AWS Partner Credits",
      "program": ["AWS Partner Network"]
    }
  }
}
```