# 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 という 2 つの主要な 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 マネージメントコンソールを使用するときは、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-legged の OAuth 2.0 とみなされます。AWS Glue は、クライアント ID とクライアントシークレットを使用して、定義したカスタムサービスによって提供される Salesforce Commerce Cloud API を認可できます。 + 各カスタムサービスは、特定のアクションを実行することをサービスに許可する一連のロールとアクセス許可を持つ API 専用ユーザーによって所有されます。アクセストークンは 1 つのカスタムサービスに関連付けられています。 + このグラントタイプは、有効期間が短いアクセストークンになり、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. OAuth スコープを指定します。オプションで、接続する Salesforce Commerce Cloud の [ユーザーマネージドクライアントアプリケーション ClientId] を入力します。 1. AWS Glue でこの接続に使用する `secretName` を選択して、トークンを配置します。 1. ネットワークを使用する場合は、ネットワークオプションを選択します。 1. AWS Glue ジョブに関連付けられている IAM ロールに `secretName` を読み取るアクセス許可を付与します。 1. AWS Glue ジョブ設定で、**[追加のネットワーク接続]** として `connectionName` を指定します。 # Salesforce Commerce Cloud エンティティからの読み取り **前提条件** + 読み取り元の Salesforce Commerce Cloud オブジェクト。使用可能なエンティティを確認するには、以下のサポートされているエンティティの表を参照してください。 **サポートされているエンティティ** | エンティティ | フィルタリング可能 | 制限をサポートする | Order By をサポートする | Select \$1 をサポートする | パーティショニングをサポートする | | --- | --- | --- | --- | --- | --- | | 割り当て | はい | あり | あり | あり | あり | | キャンペーン | はい | あり | あり | あり | あり | | カタログ | はい | あり | あり | あり | あり | | カテゴリ | はい | あり | あり | あり | あり | | Coupons | はい | あり | あり | あり | あり | | ギフト券 | はい | あり | あり | あり | あり | | 製品 | はい | あり | あり | あり | あり | | プロモーション | はい | あり | あり | あり | あり | | ソースコードグループ | はい | あり | あり | あり | あり | **例** ``` 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 エンティティとフィールドの詳細** エンティティリスト: + 割り当て:[ https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments ]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments) + キャンペーン:[ https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns ](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns) + カタログ:[ https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs ](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs) + カテゴリ:[ https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories ](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories) + ギフト券:[ https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates ](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates) + 製品:[ https://developer.salesforce.com/docs/commerce/commerce-api/references/products ](https://developer.salesforce.com/docs/commerce/commerce-api/references/products) + プロモーション:[ https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions ](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions) + ソースコードグループ:[ 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`: パーティション数。 エンティティごとのパーティション分割フィールドのサポートの詳細は、以下の表にまとめられています。 | エンティティ | Partitioning Field | DataType | | --- | --- | --- | | キャンペーン | lastModified | DateTime | | キャンペーン | startDate | DateTime | | キャンペーン | endDate | DateTime | | カタログ | creationDate | DateTime | | カテゴリ | creationDate | DateTime | | ギフト券 | merchantId | 文字列 | | ギフト券 | creationDate | DateTime | | 製品 | creationDate | DateTime | | 製品 | lastModified | DateTime | | ソースコードグループ | creationDate | DateTime | | ソースコードグループ | startTime | DateTime | | ソースコードグループ | 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) – Default: empty(SELECT \$1). 読み込みに使用されます。オブジェクトに選択する列です。 + `FILTER_PREDICATE`(文字列) – デフォルト: 空 読み込みに使用されます。Spark SQL 形式である必要があります。 + `QUERY`(文字列) - デフォルト: 空 読み込みに使用されます。完全な Spark SQL クエリです。 + `PARTITION_FIELD`(文字列) - 読み取りに使用されます。クエリをパーティション化するために使用するフィールドです。 + `LOWER_BOUND`(文字列) - 読み取りに使用されます。選択したパーティションフィールドの包括的な下限値。 + `UPPER_BOUND` (文字列) - 読み取りに使用されます。選択したパーティションフィールドの排他的上限値。 + `NUM_PARTITIONS`(整数) – デフォルト: 1。読み込みに使用されます。読み取り用のパーティションの数です。 # 制限 Salesforce Commerce Cloud コネクタの制限は次のとおりです。 + パーティショニング時、[次を含む] フィルターが期待どおりに機能しません。 + CDN ゾーンのエンティティはサンドボックスインスタンスをサポートしておらず、開発インスタンスタイプと本番インスタンスタイプのみをサポートしています。詳細については、[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)」を参照してください。 + 次の表に示すように、異なる演算子の組み合わせを使用して、1 つの API リクエストで最大 2 つのフィールド (存在する場合はレベルを除く) にフィルターを適用できます。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) + 一部のエンティティでは、取得中のフィールドのデータ型が、検索可能なフィールドとして使用される場合のデータ型と異なります。そのため、これらのフィールドにはフィルター機能のプロビジョニングがありません。このようなフィールドの詳細を次の表に示します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)