# Salesforce Commerce Cloud에 연결 B2C Commerce API는 B2C Commerce 인스턴스와 상호 작용하기 위한 RESTful API 모음입니다. Salesforce Commerce API와 그 약어인 SCAPI, 또는 Commerce API라고도 합니다. API를 통해 개발자는 전체 스토어프론트부터 사용자 지정 판매자 도구, Business Manager 강화에 이르기까지 다양한 애플리케이션을 구축할 수 있습니다. 모든 B2C Commerce 고객의 경우 API를 추가 비용 없이 사용할 수 있습니다. API는 Shopper API와 Admin API로 나뉩니다. 그리고 각 그룹 내에서 API 패밀리와 관련 기능에 초점을 맞춘 소규모 그룹으로 나뉩니다. **Topics** + [AWS Glue의 Salesforce Commerce Cloud에 지원](salesforce-commerce-cloud-support.md) + [연결을 생성하고 사용하기 위한 API 작업이 포함된 정책](salesforce-commerce-cloud-configuring-iam-permissions.md) + [Salesforce Commerce Cloud 구성](salesforce-commerce-cloud-configuring.md) + [Salesforce Commerce Cloud 연결 구성](salesforce-commerce-cloud-configuring-connections.md) + [Salesforce Commerce Cloud 엔터티에서 읽기](salesforce-commerce-cloud-reading-from-entities.md) + [Salesforce Commerce Cloud 연결 옵션 참조](salesforce-commerce-cloud-connection-options.md) + [제한 사항](salesforce-commerce-cloud-connector-limitations.md) # AWS Glue의 Salesforce Commerce Cloud에 지원 AWS Glue에서는 다음과 같이 Salesforce Commerce Cloud를 지원합니다. **소스로 지원되나요?** 예. AWS Glue ETL 작업을 사용하여 Salesforce Commerce Cloud에서 데이터를 쿼리할 수 있습니다. **대상으로서 지원되나요?** 아니요. **지원되는 Salesforce Commerce Cloud API 버전** v1. # 연결을 생성하고 사용하기 위한 API 작업이 포함된 정책 다음 샘플 정책에서는 연결을 생성하고 사용하는 데 필요한 AWS 권한을 설명합니다. 새 역할을 생성하는 경우 다음을 포함하는 정책을 생성합니다. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ 아래 관리형 IAM 정책을 사용하여 다음에 대한 액세스를 허용할 수 있습니다. + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – 다양한 AWS Glue 프로세스를 대신 실행하는 데 필요한 리소스에 대한 액세스 권한을 부여합니다. 이러한 리소스에는 AWS Glue, Amazon S3, IAM, CloudWatch Logs 및 Amazon EC2가 포함됩니다. 이 정책에 지정된 리소스의 이름 변환을 따르고자 한다면 AWS Glue 절차는 필요한 권한을 소유합니다. 이 정책은 크롤러, 작업 및 개발 엔드포인트를 정의할 때 지정된 역할에 일반적으로 추가됩니다. + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) - 정책이 연결된 자격 증명이 AWS Management Console을 사용하는 경우 AWS Glue 리소스에 대한 전체 액세스 권한을 부여합니다. 이 정책에 지정된 리소스의 이름 변환을 따르면 사용자는 콘솔 전체 용량을 소유합니다. 이 정책은 보통 AWS Glue 콘솔의 사용자에게 해당됩니다. # Salesforce Commerce Cloud 구성 AWS Glue를 사용하여 Salesforce Commerce Cloud에서 데이터를 전송하려면 먼저 다음 요구 사항을 충족해야 합니다. ## 최소 요구 사항 + clientId 및 clientSecret이 있는 Salesforce Commerce Cloud 클라이언트 애플리케이션이 있습니다. + Salesforce Commerce Cloud 계정이 API 액세스에 대해 활성화되어 있습니다. 이러한 요구 사항을 충족하면 Salesforce Commerce Cloud 계정에 AWS Glue를 연결할 준비가 된 것입니다. 일반적인 연결의 경우 Salesforce Commerce Cloud에서 다른 작업을 수행하지 않아도 됩니다. # Salesforce Commerce Cloud 연결 구성 Salesforce Commerce Cloud는 OAuth2에 대한 CLIENT CREDENTIALS 권한 부여 유형을 지원합니다. + 이 권한 부여 유형은 클라이언트가 사용자의 컨텍스트 외부에서 액세스 토큰을 얻는 데 사용하므로 2각 OAuth 2.0으로 간주됩니다. AWS Glue는 클라이언트 ID와 클라이언트 보안 암호를 사용하여 사용자가 정의한 사용자 지정 서비스에서 제공하는 Salesforce Commerce Cloud API를 인증할 수 있습니다. + 각 사용자 지정 서비스는 API 전용 사용자가 소유하며, API 전용 사용자는 서비스에 특정 작업을 수행하도록 권한을 부여하는 역할 및 권한 집합을 가집니다. 액세스 토큰은 단일 사용자 지정 서비스와 연결됩니다. + 이 권한 부여 유형은 수명이 짧은 액세스 토큰을 생성하며 ID 엔드포인트를 호출하여 갱신할 수 있습니다. + 클라이언트 자격 증명 생성에 대한 Salesforce Commerce Cloud 설명서에서 정보를 찾으려면 [Salesforce 설명서](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html)를 참조하세요. 다음 단계를 따라 Salesforce Commerce Cloud 연결을 구성합니다. 1. AWS Secrets Manager에서 다음 세부 정보를 사용하여 보안 암호를 생성합니다. AWS Glue에서 각 연결에 대한 보안 암호를 생성해야 합니다. 1. 고객 관리형 연결된 앱 - 보안 암호는 키 역할을 하는 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET과 함께 연결된 앱 소비자 보안 암호를 포함해야 합니다. 1. AWS Glue Studio의 **데이터 연결**에서 아래 단계에 따라 연결을 생성합니다. 1. 데이터 연결에서 **연결 생성**을 선택합니다. 1. **데이터 소스**를 선택할 때 Salesforce Commerce Cloud를 선택합니다. 1. Salesforce Commerce Cloud **단축 코드**, **조직 ID** 및 **사이트 ID**를 입력합니다. 1. Salesforce Commerce Cloud 계정의 Salesforce Commerce Cloud 도메인 URL을 선택합니다. 1. 다음 작업에 대한 권한이 있고 AWS Glue에서 수임할 수 있는 IAM 역할을 선택하세요. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 연결하려는 Salesforce Commerce Cloud의 OAuth 범위(선택 사항으로 사용자 관리형 클라이언트 애플리케이션 ClientId)를 입력합니다. 1. 토큰을 넣기 위해 AWS Glue에서 이 연결에 사용할 `secretName`을 선택합니다. 1. 네트워크를 사용하려는 경우 네트워크 옵션을 선택합니다. 1. AWS Glue 작업 권한과 연결된 IAM 역할에 `secretName`을 읽을 수 있는 권한을 부여합니다. 1. AWS Glue 작업 구성에서** 추가 네트워크 연결**로 `connectionName`을 제공합니다. # Salesforce Commerce Cloud 엔터티에서 읽기 **사전 조건** + 읽으려는 Salesforce Commerce Cloud 객체. 사용 가능한 엔터티를 확인하려면 아래 지원되는 엔터티 테이블을 참조하세요. **지원되는 엔터티** | 개체 | 필터링 가능 | 제한 지원 | 정렬 기준 지원 | Select \$1 지원 | 분할 지원 | | --- | --- | --- | --- | --- | --- | | Assignments | 예 | 예 | 예 | 예 | 예 | | Campaigns | 예 | 예 | 예 | 예 | 예 | | Catalogs | 예 | 예 | 예 | 예 | 예 | | Categories | 예 | 예 | 예 | 예 | 예 | | Coupons | 예 | 예 | 예 | 예 | 예 | | Gift Certificates | 예 | 예 | 예 | 예 | 예 | | Products | 예 | 예 | 예 | 예 | 예 | | Promotions | 예 | 예 | 예 | 예 | 예 | | Source Code Groups | 예 | 예 | 예 | 예 | 예 | **예제** ``` salesforce_commerce_cloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "campaign", "API_VERSION": "v1" } ) ``` **Salesforce Commerce Cloud 엔터티 및 필드 세부 정보** 엔터티 목록: + Assignments: [https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments) + Campaigns: [https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns) + Catalogs: [https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs) + Categories: [https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories) + Gift Certificates: [https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates) + Products: [https://developer.salesforce.com/docs/commerce/commerce-api/references/products](https://developer.salesforce.com/docs/commerce/commerce-api/references/products) + Promotions: [https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions) + Source Code Groups: [https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups](https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups) **분할 쿼리** Spark에서 동시성을 활용하려는 경우 추가 Spark 옵션(`PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND`, `NUM_PARTITIONS`)을 제공할 수 있습니다. 이러한 파라미터를 사용하면 Spark 태스크에서 동시에 실행할 수 있는 `NUM_PARTITIONS`개의 하위 쿼리로 원본 쿼리가 분할됩니다. + `PARTITION_FIELD`: 쿼리 분할에 사용할 필드의 이름입니다. + `LOWER_BOUND`: 선택한 파티션 필드의 하한 값(경계 포함). 날짜의 경우 Spark SQL 쿼리에 사용된 Spark 날짜 형식을 허용합니다. 유효한 값의 예제: `"2024-02-06"`. + `UPPER_BOUND`: 선택한 파티션 필드의 상한 값(경계 제외). + `NUM_PARTITIONS`: 파티션 수. 엔터티 수준 분할 필드 지원 세부 정보는 아래 표에 나와 있습니다. | 개체 | 분할 필드 | 데이터 유형 | | --- | --- | --- | | Campaigns | lastModified | DateTime | | Campaigns | startDate | DateTime | | Campaigns | endDate | DateTime | | Catalogs | creationDate | DateTime | | Categories | creatiionDate | DateTime | | Gift Certificates | merchantId | String | | Gift Certificates | creatiionDate | DateTime | | Products | creatiionDate | DateTime | | Products | lastModified | DateTime | | Source Code Groups | creationDate | DateTime | | Source Code Groups | startTime | DateTime | | Source Code Groups | endTime | DateTime | **예제** ``` salesforceCommerceCloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupons", "API_VERSION": "v1", "PARTITION_FIELD": "creationDate", "LOWER_BOUND": "2020-05-01T20:55:02.000Z", "UPPER_BOUND": "2024-07-11T20:55:02.000Z", "NUM_PARTITIONS": "10" } ) ``` # Salesforce Commerce Cloud 연결 옵션 참조 다음은 Salesforce Commerce Cloud의 연결 옵션입니다. + `ENTITY_NAME`(문자열) - (필수) 읽기에 사용됩니다. Salesforce Commerce Cloud에서의 객체 이름. + `API_VERSION`(문자열) - (필수) 읽기/쓰기에 사용됩니다. 사용하려는 Salesforce Commerce Cloud Rest API 버전. 예: v1. + `SELECTED_FIELDS`(List) - 기본값: 비어 있습니다(SELECT \$1). 읽기에 사용됩니다. 객체에 대해 선택할 열. + `FILTER_PREDICATE`(문자열) - 기본값: 비어 있습니다. 읽기에 사용됩니다. Spark SQL 형식이어야 합니다. + `QUERY`(문자열) - 기본값: 비어 있습니다. 읽기에 사용됩니다. 전체 Spark SQL 쿼리. + `PARTITION_FIELD`(문자열) - 읽기에 사용됩니다. 쿼리 분할에 사용할 필드입니다. + `LOWER_BOUND`(문자열) - 읽기에 사용됩니다. 선택한 파티션 필드의 하한 값(경계 포함). + `UPPER_BOUND`(문자열) - 읽기에 사용됩니다. 선택한 파티션 필드의 상한 값(경계 제외). + `NUM_PARTITIONS`(정수) - 기본값: 1. 읽기에 사용됩니다. 읽을 파티션 수. # 제한 사항 다음은 Salesforce Commerce Cloud 커넥터의 제한 사항입니다. + 분할 시 Contains 필터가 예상대로 작동하지 않습니다. + CDN Zones의 엔터티는 샌드박스 인스턴스를 지원하지 않으며, 개발 및 프로덕션 인스턴스 유형만 지원합니다. 자세한 내용은 [https://help.salesforce.com/s/articleView?id=cc.b2c\$1embedded\$1cdn\$1overview.htm](https://help.salesforce.com/s/articleView?id=cc.b2c_embedded_cdn_overview.htm) 페이지를 참조하세요. + Salesforce Commerce Cloud에서 동적 메타데이터를 가져올 API 엔드포인트가 없습니다. 따라서 제품 및 카테고리 엔터티의 사용자 지정 필드를 지원하는 프로비저닝이 없습니다. + 사이트 ID는 필수 쿼리 파라미터입니다. 사용자 지정 커넥터 설정을 통해 사이트 ID 값을 전달해야 합니다. 자세한 내용은 [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)을 참조하세요. + 아래 표에 언급된 대로 서로 다른 연산자를 조합하여 단일 API 요청에서 최대 두 개의 필드(있는 경우 Levels 제외)에 필터를 적용할 수 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) + 일부 엔터티에서 검색할 때 필드의 데이터 유형은 검색 가능한 필드로 사용되는 경우와 다릅니다. 그에 따라 이러한 필드에는 필터 특성의 프로비저닝이 없습니다. 다음 표에는 이러한 필드에 대한 세부 정보가 나와 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)