# SAP OData への接続
SAP OData は、ABAP (Advanced Business Application Programming) を使用して SAP に存在するデータをクエリおよび更新するために使用される標準のウェブプロトコルです。HTTP などのウェブテクノロジーを適用して構築し、さまざまな外部アプリケーション、プラットフォーム、デバイスからの情報へのアクセスを提供します。製品を使用すると、SAP システム、アプリケーション、またはデータとシームレスに統合するために必要なすべてにアクセスできます。
**Topics**
+ [AWS Glue による SAP OData のサポート](sap-odata-support.md)
+ [接続を作成する](sap-odata-creating-connections.md)
+ [SAP OData ジョブの作成](sap-odata-creating-job.md)
+ [SAP OData への書き込み](sap-odata-writing.md)
+ [SAP OData 状態管理スクリプトの使用](sap-odata-state-management-script.md)
+ [ODP 非対応エンティティのパーティション分割](sap-odata-non-odp-entities-partitioning.md)
+ [SAP OData 接続オプション](sap-odata-connection-options.md)
+ [SAP OData エンティティとフィールドの詳細](sap-odata-entity-field-details.md)
# AWS Glue による SAP OData のサポート
AWS Glue は SAP OData を次のようにサポートします:
**ソースとしてサポートされていますか?**
はい。AWS Glue ETL ジョブを使用して、SAP OData からデータをクエリできます。
**ターゲットとしてサポートされているかどうか**
はい。AWS Glue ETL ジョブを使用して SAP OData にレコードを書き込むことができます。
**サポートされている SAP OData API バージョン**
次の SAP OData API バージョンがサポートされています:
+ 2.0
**サポートされているソース**
以下のソースがサポートされています。
+ ODP (オペレーショナルデータプロビジョニング) ソース：
+ BW Extractor (DataSources)
+ CDS ビュー
+ SLT
+ ODP 非対応ソース。例：
+ CDS ビューサービス
+ RFC ベースのサービス
+ カスタム ABAP サービス
**サポートされている SAP コンポーネント**
以下に、最小要件を示します。
+ サービス検出のためにカタログサービスを有効にする必要があります。
+ SAP システムの SAP Gateway で、抽出するオペレーショナルデータプロビジョニング (ODP) データソースを設定します。
+ **OData V2.0**: トランザクション `/IWFND/MAINT_SERVICE` を介して SAP Gateway で OData V2.0 カタログサービス (複数可) を有効にします。
+ トランザクション `/IWFND/MAINT_SERVICE` を介して SAP Gateway で OData V2.0 サービスを有効にします。
+ SAP OData サービスは、`$top` や `$skip` などのクライアント側のページ分割/クエリオプションをサポートしている必要があります。また、システムクエリオプション `$count` もサポートする必要があります。
+ ユーザーが SAP OData サービスを検索し、データ抽出を行えるようにするには、ユーザーに適切な権限を付与する必要があります。SAP が提供するセキュリティドキュメントを参照してください。
+ OAuth 2.0 を認証メカニズムとして使用する場合は、OData サービスに対して OAuth 2.0 を有効にし、SAP ドキュメントに従って OAuth クライアントを登録する必要があります。
+ ODP データソースに基づいて OData サービスを生成するには、SAP Gateway Foundation を ERP/BW スタックまたはハブの設定にローカルにインストールする必要があります。
+ ERP/BW アプリケーションの場合、SAP NetWeaver AS ABAP スタックは 7.50 SP02 以上である必要があります。
+ ハブシステム (SAP Gateway) の場合、リモートハブのセットアップには、ハブシステムの SAP NetWeaver AS ABAP が 7.50 SP01 以上である必要があります。
+ ODP 非対応ソースの場合、SAP NetWeaver スタックのバージョンは 7.40 SP02 以降である必要があります。
**サポートされた認証方法**
次の認証方法がサポートされています。
+ 基本認証
+ OAuth 2.0
# 前提条件
SAP OData 接続を使用して SAP OData からデータ抽出する AWS Glue ジョブを開始する前に、次の前提条件を満たしてください。
+ 関連する SAP OData Service を SAP システムでアクティブ化し、データソースを使用できることを確認する必要があります。OData サービスがアクティブ化されていない場合、 Glue ジョブは SAP からデータにアクセスまたは抽出できません。
+ AWS Glue ジョブが SAP OData サービスとの接続を正常に確立できるように、基本 (カスタム) 認証や OAuth 2.0 などの適切な認証メカニズムを SAP で設定する必要があります。
+ IAM ポリシーを設定して、SAP、Secrets Manager、およびプロセスに関連するその他の AWS リソースにアクセスするための適切なアクセス許可を AWS Glue ジョブに付与します。
+ SAP システムがプライベートネットワーク内でホストされている場合、AWS Glue ジョブがパブリックインターネット経由で機密データを公開することなく SAP と安全に通信できるように VPC 接続を設定する必要があります。
AWS Secrets Manager を使用して、AWS Glue ジョブが実行時に動的に取得できる SAP 認証情報などの機密情報を安全に保存できます。このアプローチにより、認証情報をハードコードする必要がなくなり、セキュリティと柔軟性が向上します。
以下の前提条件は、 AWS Glue と SAP OData をスムーズに統合するために各コンポーネントを設定する方法に関するステップごとのガイダンスを提供します。
**Topics**
+ [SAP OData のアクティベーション](sap-odata-activation.md)
+ [IAM ポリシー](sap-odata-configuring-iam-permissions.md)
+ [接続 / VPC 接続](sap-odata-connectivity-vpc-connection.md)
+ [SAP 認証](sap-odata-authentication.md)
+ [認証シークレットを保存する AWS Secrets Manager](sap-odata-aws-secret-manager-auth-secret.md)
# SAP OData のアクティベーション
SAP OData 接続には、次の手順を実行します。
## ODP ソース
ODP プロバイダーからデータを転送する前に、次の要件を満たす必要があります。
+ お客様のSAP NetWeaver AS ABAP インスタンスには、
+ データ転送元の ODP プロバイダーが含まれています。ODP プロバイダーには以下が含まれます。
+ SAP DataSources (トランザクションコード RSO2)
+ SAP Core Data Services ABAP CDS ビュー
+ SAP BW または SAP BW/4HANA システム (InfoObject、DataStore Object)
+ SAP Landscape Replication Server (SAP SLT) を介した SAP ソースシステムからのテーブルと DB ビューのリアルタイムレプリケーション
+ SAP ABAP ベースのソースの SAP HANA Information ビュー
+ SAP NetWeaver インスタンスには SAP Gateway Foundation コンポーネントが含まれています。
+ ODP プロバイダーからデータを抽出する OData サービスを作成しました。OData サービスを作成するには、SAP Gateway Service Builder を使用します。ODP データにアクセスするには、Amazon AppFlow が OData API を使用してこのサービスを呼び出します。詳細については、SAP BW/4HANA ドキュメントの「[Generating a Service for Extracting ODP Data via OData](https://help.sap.com/docs/SAP_BPC_VERSION_BW4HANA/dd104a87ab9249968e6279e61378ff66/69b481859ef34bab9cc7d449e6fff7b6.html?version=11.0)」を参照してください。
+ ODP データソースに基づいて OData サービスを生成するには、SAP Gateway Foundation を ERP/BW スタックまたはハブの設定にローカルにインストールする必要があります。
+ ERP/BW アプリケーションの場合、SAP NetWeaver AS ABAP スタックは 7.50 SP02 以上である必要があります。
+ ハブシステム (SAP Gateway) の場合、リモートハブのセットアップには、ハブシステムの SAP NetWeaver AS ABAP が 7.50 SP01 以上である必要があります。
## ODP 非対応ソース
+ SAP NetWeaver スタックのバージョンは 7.40 SP02 以降である必要があります。
+ サービス検出のためにカタログサービスを有効にする必要があります。
+ **OData V2.0**: OData V2.0 カタログサービスは、トランザクション `/IWFND/MAINT_SERVICE` を介して SAP ゲートウェイで有効にすることができます。
+ SAP OData サービスは、`$top` や `$skip` などのクライアント側のページ分割/クエリオプションをサポートしている必要があります。また、システムクエリオプション `$count` もサポートする必要があります。
+ OAuth 2.0 の場合、OData サービスで OAuth 2.0 を有効にし、SAP ドキュメントに従って OAuth クライアントを登録し、承認されたリダイレクト URL を次のように設定する必要があります。
+ `https://.console.aws.amazon.com/gluestudio/oauth`、 AWS Glue を `` が実行されているリージョン（例：us-east-1）に置き換えます。
+ HTTPS 経由で接続するには、安全なセットアップを有効にする必要があります。
+ ユーザーが SAP OData サービスを検索し、データ抽出を行えるようにするには、ユーザーに適切な権限を付与する必要があります。SAP が提供するセキュリティドキュメントを参照してください。
# IAM ポリシー
## 接続を作成および使用するための API オペレーションを含むポリシー
次のサンプル ポリシーで、接続の作成と使用に必要な AWS IAM 権限について説明します。新しいロールを作成する場合は、以下を含むポリシーを作成します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue"
],
"Resource": "*"
}
]
}
```
------
ロールは、Amazon S3 など、ジョブで使用されるすべてのリソースへのアクセスを許可する必要があります。上記の方法を使用しない場合は、代わりに次のマネージド 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 コンソールのユーザーにアタッチされています。
+ [SecretsManagerReadWrite](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/SecretsManagerReadWrite) — AWS マネジメントコンソール経由で AWS Secrets Manager への読み取り/書き込みアクセスを提供します。注: これには IAM アクションは含まれないため、ローテーション設定が必要な場合は `IAMFullAccess` と組み合わせてください。
**VPC の設定に必要な IAM ポリシー/アクセス許可**
AWS Glue 接続を作成するために VPC 接続を使用する場合は、次の IAM アクセス許可が必要です。詳細については、「[AWS Glue の IAM ポリシーを作成する](https://docs.aws.amazon.com/glue/latest/dg/create-service-policy.html)」を参照してください。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"*"
]
}
]
}
```
------
# 接続 / VPC 接続
VPC 接続の手順:
1. 既存の VPC 接続を使用するか、[Amazon VPC ドキュメント](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html)に従って新しい接続を作成します。
1. トラフィックをインターネットにルーティングする NAT Gateway があることを確認します。
1. 接続を作成するには、VPC エンドポイントを Amazon S3 Gateway として選択します。
1. AWS が提供する DNS サービスを使用するには、DNS 解決と DNS ホスト名を有効にします。
1. 作成した VPC に移動し、STS、AWS Glue、シークレットマネージャーなどのさまざまなサービスに必要なエンドポイントを追加します。
1. [Create Endpoint] (エンドポイントの作成) を選択します。
1. [サービスカテゴリ] では、[AWS サービス] を選択する。
1. [Service Name] で、接続先のサービスを選択します。
1. VPC を選択し、DNS 名を有効にします。
1. VPC 接続に必要な VCP エンドポイント:
1. [STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sts_vpc_endpoint_create.html)
1. [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html)
1. [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)
## セキュリティグループの設定
AWS Glue がセキュリティ グループに接続できるようにするには、セキュリティ グループで AWS Glue VPC からのリスニング ポートへのトラフィックを許可する必要があります。ソース IP アドレスの範囲をできるだけ制限することをお勧めします。
AWS Glue には、それ自体からのすべてのインバウンドトラフィックを許可する特別なセキュリティグループが必要です。セキュリティグループから発信されるすべてのトラフィックを許可する自己参照ルールを作成できます。既存のセキュリティグループを変更し、ソースとしてセキュリティグループを指定できます。
URL エンドポイント (NLB または SAP インスタンス) の HTTPS ポートから通信を開きます。
## 接続オプション
+ 内部および外部 NLB との HTTPS 接続、認証局 (CA) からの SSL 証明書 (自己署名 SSL 証明書ではない)
+ 自己署名 SSL 証明書ではなく、認証局 (CA) からの SAP インスタンス SSL 証明書を使用した HTTPS 接続
# SAP 認証
SAP コネクタは、CUSTOM (SAP BASIC 認証) と OAUTH 認証の両方の方法をサポートしています。
## カスタム認証
AWS Glue は、SAP システムへの接続を確立するための方法としてカスタム (基本認証) をサポートし、ユーザー名とパスワードを使用して安全なアクセスを可能にします。この認証タイプは、SAP OData インスタンス内の特定のユーザーのアクセス許可でユーザー名とパスワードを事前に使用できるため、自動化シナリオに適しています。AWS Glue はユーザー名とパスワードを使用して SAP OData APIs を認証できます。AWS Glue では、基本認可はカスタム認可として実装されます。
基本的な認証フローに関する SAP OData のパブリックドキュメントについては、「[HTTP Basic Authentication](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/5c8bca0af1654b05a83193b2922dcee2.html)」を参照してください。
## OAuth 2.0 認証
AWS Glue は、SAP システムへの接続を確立するための安全な認証メカニズムとして OAuth 2.0 もサポートしています。これにより、最新の認証標準への準拠を確保し、データアクセスのセキュリティを強化しながら、シームレスな統合が可能になります。
## AUTHORIZATION\$1CODE のグラントタイプ
グラントタイプは、AWS Glue が SAP OData と通信してデータへのアクセスをリクエストする方法を決定します。SAP OData は、`AUTHORIZATION_CODE` 許可タイプのみをサポートします。このグラントタイプは、ユーザーを認証するためにサードパーティーの認証サーバーにユーザーをリダイレクトすることに依存するため、「three-legged」の OAuth と見なされます。AWS Glue コンソール経由で接続を作成するときに使用されます。
ユーザーは、SAP OData で独自の接続アプリを作成し、AWS Glue コンソールを介して接続を作成するときに独自のクライアント ID とクライアントシークレットを指定することを選択できます。このシナリオでは、引き続き SAP OData にリダイレクトされてログインし、リソースへアクセスするために AWS Glue を承認します。
このグラントタイプは、更新トークンとアクセストークンになります。アクセストークンの有効期間は短く、更新トークンを使用してユーザーとやり取りすることなく自動的に更新される場合があります。
認可コード OAuth フロー用の接続アプリの作成に関する SAP OData の公開ドキュメントについては、「[Authentication Using OAuth 2.0](https://help.sap.com/docs/ABAP_PLATFORM_NEW/e815bb97839a4d83be6c4fca48ee5777/2e5104fd87ff452b9acb247bd02b9f9e.html)」を参照してください。
# 認証シークレットを保存する AWS Secrets Manager
SAP OData 接続シークレットを AWS Secrets Manager に保存し、 [IAM ポリシー](sap-odata-configuring-iam-permissions.md) セクションで指定されているように取得に必要なアクセス許可を設定し、接続の作成時に使用する必要があります。
AWS Secrets Manager の AWS マネジメントコンソールを使用して、SAP ソースのシークレットを作成します。詳細については、「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。AWS Secrets Manager の詳細には、次のコードの要素を含める必要があります。
## カスタム認証シークレット
** の代わりに SAP システムのユーザー名を入力し、** の代わりにパスワードを入力して、True または False を入力する必要があります。このコンテキストでは、 `basicAuthDisableSSO` を `true` に設定すると、基本認証リクエストのシングルサインオン (SSO) が無効になり、リクエストごとに明示的なユーザー認証情報が必要になります。逆に、それを `false` に設定すると、利用可能な既存の SSO セッションを使用できるようになります。
```
{
"basicAuthUsername": "",
"basicAuthPassword": "",
"basicAuthDisableSSO": "",
"customAuthenticationType": "CustomBasicAuth"
}
```
## OAuth 2.0 シークレット
認証メカニズムとして OAuth 2.0 を使用している場合、AWS Secrets Manager のシークレットには、次の形式の **ユーザーマネージドクライアントアプリケーション ClientId** が必要です。＜クライアントシークレット> の代わりに SAP クライアントシークレットを入力する必要があります。
```
{"USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET": ""
}
```
# 接続を作成する
SAP OData 接続を設定するには
1. AWS マネジメントコンソールにサインインし、[AWS Glue コンソール](https://console.aws.amazon.com/glue)を開きます。AWS Glue Studio で、以下の手順に従って接続を作成します。
1. 左側のパネルでデータ接続をクリックします。
1. [接続を作成] をクリックします。
1. **[データソースを選択]** で **[SAP OData]** を選択します。
1. 接続先の SAP OData インスタンスの **[アプリケーションホスト URL]** を指定します。このアプリケーションホスト URL は、VPC 以外の接続ではパブリックインターネット経由でアクセス可能である必要があります。
1. 接続先の SAP OData インスタンスの **[アプリケーションサービスパス]** を指定します。これはカタログサービスのパスと同じです。例: `/sap/opu/odata/iwfnd/catalogservice;v=2`。 AWS Glue は特定のオブジェクトのパスを受け入れません。
1. 接続先の SAP OData インスタンスの **[クライアント番号]** を指定します。指定できる値は、001 から 999 です。例：010
1. 接続先の SAP OData インスタンスの **[ポート番号]** を指定します。例: 443
1. 接続先の SAP OData インスタンスの **[ログオン言語]** を指定します。EN の例
1. 「[IAM ポリシー](sap-odata-configuring-iam-permissions.md)」セクションで説明しているように、AWS Glue が引き受けることができ、かつアクセス許可を持つ AWS IAM ロールを選択します。
1. AWS Glue でこの接続に使用する **[認証タイプ]** をドロップダウンリストから選択してください。選択肢は OAUTH2 または CUSTOM です。
1. CUSTOM - 「[認証シークレットを保存する AWS Secrets Manager](sap-odata-aws-secret-manager-auth-secret.md)」セクションで指定したとおりに作成したシークレットを選択します。
1. OAUTH 2.0 - OAuth 2.0 を使用する場合のみ、以下の情報を入力します。
1. **[ユーザーマネージドクライアントアプリケーション ClientId]** に、クライアント ID を入力します。
1. [認証シークレットを保存する AWS Secrets Manager](sap-odata-aws-secret-manager-auth-secret.md) セクションで作成した AWS Secrets Manager の `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` (クライアントシークレット)。
1. **[認証コードの URL]** に、認証コードの URL を入力します。
1. **[認証トークン URL]** に、認証トークンの URL を入力します。
1. **[OAuth スコープ]** で、OAuth スコープをスペースで区切って入力します。例:`/IWFND/SG_MED_CATALOG_0002 ZAPI_SALES_ORDER_SRV_0001`
1. ネットワークを使用する場合は、ネットワークオプションを選択します。詳細については、「[接続 / VPC 接続](sap-odata-connectivity-vpc-connection.md)」を参照してください。
1. AWS Glue ジョブに関連付けられている IAM ロールに `secretName` を読み取るアクセス許可を付与します。詳細については、「[IAM ポリシー](sap-odata-configuring-iam-permissions.md)」を参照してください。
1. **[接続のテスト]** を選択し、接続をテストします。接続テストに合格したら、[次へ] をクリックし、接続名を入力して接続を保存します。ネットワークオプション (VPC) を選択した場合、テスト接続機能は使用できません。
# SAP OData ジョブの作成
「[AWS Glue Studio でビジュアル ETL ジョブを作成する](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)」を参照してください。
# オペレーショナルデータプロビジョニング (ODP) ソース
オペレーショナルデータプロビジョニング (ODP) は、さまざまなターゲットアプリケーションのデータ抽出とレプリケーションをサポートするために使用できる技術インフラストラクチャを提供し、これらのシナリオでデルタメカニズムをサポートします。デルタプロシージャの場合、ソース (ODP プロバイダー) からのデータは、更新プロセスを使用してデルタキュー (オペレーションデルタキュー – ODQ) に自動的に書き込まれるか、エクストラクタインターフェイスを使用してデルタキューに渡されます。ODP プロバイダーは、DataSource (エクストラクター）、ABAP Core Data Services ビュー (ABAP CDS ビュー）、SAP BW または SAP BW/4HANA、SAP Landscape Transformation Replication Server (SLT)、SAP HANA Information ビュー (計算ビュー) のいずれかです。ターゲットアプリケーション (ODQ の「サブスクライバー」またはより一般的には「ODP コンシューマー」と呼ばれる) は、デルタキューからデータを取得し、データの処理を続行します。
## フルロード
SAP OData エンティティおよび ODP エンティティのコンテキストにおいて、**フルロード**とは、1 回のオペレーションで ODP エンティティから使用可能なすべてのデータを抽出するプロセスを指します。このオペレーションは、ソースシステムから完全なデータセットを取得し、ターゲットシステムにエンティティのデータの包括的かつ最新のコピーが確実に保持されます。通常、全ロードは、増分ロードをサポートしないソースや、ターゲットシステムの更新が必要な場合に使用されます。
**例**
DynamicFrame を作成するときに、明示的に `ENABLE_CDC` フラグを false に設定できます。注: `ENABLE_CDC` はデフォルトで false です。デルタキューを初期化しない場合は、このフラグを送信したり true に設定したりする必要はありません。このフラグを true に設定しないと、全ロード抽出になります。
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "false"
}, transformation_ctx=key)
```
## 増分ロード
ODP (オペレーショナルデータプロビジョニング) エンティティのコンテキストでの**増分ロード**では、前回のデータ抽出以降にソースシステムから新規または変更されたデータ (デルタ) のみを抽出し、すでに処理されたレコードを前処理しないようにします。このアプローチにより、効率が大幅に向上し、データ転送量が削減され、パフォーマンスが向上し、システム間の効率的な同期が保証され、特に頻繁に変更される大規模なデータセットの場合、処理時間が最小限に抑えられます
# デルタトークンベースの増分転送
変更データキャプチャ (CDC) を使用して、それをサポートする ODP 対応エンティティの増分転送を有効にするには、次の手順に従います。
1. スクリプトモードで増分転送ジョブを作成します。
1. DataFrame または Glue DynamicFrame を作成する際には、オプション `"ENABLE_CDC": "True"` を渡す必要があります。このオプションにより、SAP からデルタトークンを受信できます。このトークンは、変更後のデータの取得に使用できます。
データフレームの最後の行の DELTA\$1TOKEN 列に格納されます。このトークンは、後続の呼び出しでコネクタ オプションとして使用して、次のデータ セットを段階的に取得できます。
**例**
+ DynamicFrameを作成する際に、`ENABLE_CDC` フラグを `true` に設定します。注: `false` はデフォルトで `ENABLE_CDC` です。デルタキューを初期化しない場合は、このフラグを送信したり true に設定したりする必要はありません。このフラグを true に設定しないと、全ロード抽出になります。
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true"
}, transformation_ctx=key)
# Extract the delta token from the last row of the DELTA_TOKEN column
delta_token_1 = your_logic_to_extract_delta_token(sapodata_df) # e.g., D20241029164449_000370000
```
+ 抽出されたデルタトークンを新しいイベントを取得するためのオプションとして渡すことができます。
```
sapodata_df_2 = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
// passing the delta token retrieved in the last run
"DELTA_TOKEN": delta_token_1
} , transformation_ctx=key)
# Extract the new delta token for the next run
delta_token_2 = your_logic_to_extract_delta_token(sapodata_df_2)
```
`DELTA_TOKEN` が格納されている最後のレコードは、ソースからのトランザクションレコードではなく、デルタトークン値を渡す目的でのみ存在することに注意してください。
`DELTA_TOKEN` とは別に、データフレームの各行には次のフィールドが返されます。
+ **GLUE\$1FETCH\$1SQ**: これは、レコードが受信された順序で EPOC タイムスタンプから生成されるシーケンスフィールドで、レコードごとに一意です。これは、ソースシステムの変更の順序を確認または確立する必要がある場合に使用できます。このフィールドは、ODP が有効なエンティティにのみ表示されます。
+ **DML\$1STATUS**: これにより、ソースから新しく挿入および更新されたすべてのレコードに対して `UPDATED` が表示され、ソースから削除されたレコードに対して `DELETED` が表示されます。
状態を管理し、差分トークンを再利用して、変更したレコードを取得する方法の詳細については、「[SAP OData 状態管理スクリプトの使用](sap-odata-state-management-script.md)」セクションを参照してください。
## デルタトークンの無効化
デルタトークンは、サービスコレクションとユーザーに関連付けられます。同じサービスコレクションとユーザーに対して `“ENABLE_CDC” : “true”` を有効にした新しい初期プルが開始されると、以前の初期化の結果として発行された以前のデルタトークンはすべて SAP OData サービスによって無効になります。有効期限が切れたデルタトークンを使用してコネクタを呼び出すと、例外が発生します。
`Could not open data access via extraction API RODPS_REPL_ODP_OPEN`
# OData サービス (ODP 非対応ソース）
## フルロード
ODP (オペレーショナルデータプロビジョニング) に対応していないシステムの場合、**フルロード**では、ソース システムからデータセット全体を抽出し、ターゲットシステムにロードします。ODP に対応していないシステムは、差分などの高度なデータ抽出メカニズムを本質的にサポートしないため、そのプロセスは単純ですが、データのサイズによってはリソースを大量に消費する可能性があります。
## 増分ロード
**ODP (オペレーショナルデータプロビジョニング）** をサポートしていないシステムまたはエンティティの場合、変更を追跡および抽出をするためのタイムスタンプベースの仕組みを実装することで、増分データ転送を手動で管理できます。
**タイムスタンプベースの増分転送**
ODP 非対応のエンティティの場合 (または ENABLE\$1CDC フラグを使用しない ODP が有効になっているエンティティの場合)、コネクタで `filteringExpression` オプションを使用して、データを取得する `datetime` 間隔を指定できます。この方法は、各レコードが最後に作成/変更された日時を表すデータ内のタイムスタンプフィールドに依存します。
**例**
2024-01-01T00:00:00.000 後に変更されたレコードの取得
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"filteringExpression": "LastChangeDateTime >= 2024-01-01T00:00:00.000"
}, transformation_ctx=key)
```
注: この例では、`LastChangeDateTime` は各レコードが最後に変更された日時を表すフィールドです。実際のフィールド名は、特定の SAP OData エンティティによって異なる場合があります。
後続の実行でデータの新しいサブセットを取得するには、`filteringExpression` を新しいタイムスタンプで更新します。通常、これは以前に取得したデータの最大タイムスタンプ値になります。
**例**
```
max_timestamp = get_max_timestamp(sapodata_df) # Function to get the max timestamp from the previous run
next_filtering_expression = f"LastChangeDateTime > {max_timestamp}"
# Use this next_filtering_expression in your next run
```
次のセクションでは、これらのタイムスタンプベースの増分転送を管理するための自動化されたアプローチを提供し、実行間でフィルタリング式を手動で更新する必要がなくなります。
# SAP OData への書き込み
このセクションでは、SAP OData の AWS Glue コネクタを使用して SAP OData Service にデータを書き込む方法について説明します。
**前提条件**
+ SAP OData サービスへのアクセス
+ 書き込み先の SAP OData EntitySet Object。Object 名が必要になります。
+ 有効な SAP OData 認証情報と有効な接続
+ [IAM ポリシー](https://docs.aws.amazon.com/glue/latest/dg/sap-odata-configuring-iam-permissions.html)で説明されている適切なアクセス許可
SAP OData コネクタは、次の 2 つの書き込みオペレーションをサポートしています。
+ INSERT
+ UPDATE
UPDATE 書き込みオペレーションを使用する場合は、ID\$1FIELD\$1NAMES を指定してレコードの外部 ID フィールドを指定する必要があります。
**例:**
```
sapodata_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"WRITE_OPERATION": "INSERT"
}
```
# SAP OData 状態管理スクリプトの使用
AWS Glue ジョブで SAP OData 状態管理スクリプトを使用するには、次の手順に従います:
+ パブリック Amazon S3 バケットから状態管理スクリプト: `s3://aws-blogs-artifacts-public/artifacts/BDB-4789/sap_odata_state_management.zip ` をダウンロードします。
+ AWS Glue ジョブがアクセス許可を持つ Amazon S3 バケットにスクリプトをアップロードします。
+ AWS Glue ジョブ内のスクリプトを参照する: AWS Glue ジョブを作成または更新するときは、Amazon S3 バケット内のスクリプトパスを参照する `'--extra-py-files'` オプションを渡します。例: `--extra-py-files s3://your-bucket/path/to/sap_odata_state_management.py`
+ AWS Glue ジョブスクリプトで状態管理ライブラリをインポートして使用します。
## デルタトークンベースの増分転送の例
以下は、デルタトークンベースの増分転送に 状態管理スクリプトを使用する方法の例です。
```
from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType
# Initialize the state manager
state_manager = StateManagerFactory.create_manager(
manager_type=StateManagerType.JOB_TAG,
state_type=StateType.DELTA_TOKEN,
options={
"job_name": args['JOB_NAME'],
"logger": logger
}
)
# Get connector options (including delta token if available)
key = "SAPODataNode"
connector_options = state_manager.get_connector_options(key)
# Use the connector options in your Glue job
df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true",
**connector_options
}
)
# Process your data here...
# Update the state after processing
state_manager.update_state(key, sapodata_df.toDF())
```
## タイムスタンプベースの増分転送の例
以下は、デルタトークンベースの増分転送に 状態管理スクリプトを使用する方法の例です。
```
from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType
# Initialize the state manager
state_manager = StateManagerFactory.create_manager(
manager_type=StateManagerType.JOB_TAG,
state_type=StateType.DELTA_TOKEN,
options={
"job_name": args['JOB_NAME'],
"logger": logger
}
)
# Get connector options (including delta token if available)
key = "SAPODataNode"
connector_options = state_manager.get_connector_options(key)
# Use the connector options in your Glue job
df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true",
**connector_options
}
)
# Process your data here...
# Update the state after processing
state_manager.update_state(key, sapodata_df.toDF())
```
どちらの例でも、状態管理スクリプトはジョブ実行間の状態 (デルタトークンまたはタイムスタンプ) の保存の複雑さを処理します。コネクタオプションを取得するときに最後の既知の状態を自動的に取得し、処理後に状態を更新して、各ジョブ実行が新規または変更されたデータのみを処理するようにします。
# ODP 非対応エンティティのパーティション分割
Apache Spark では、パーティション分割とは、並列処理のためにクラスター内のワーカーノード間でデータを分割して分散する方法を指します。各パーティションは、タスクによって個別に処理できるデータの論理的なチャンクです。パーティショニングは、Spark の基本的な概念であり、パフォーマンス、スケーラビリティ、リソース使用率に直接影響します。 AWS Glue ジョブは、Spark のパーティショニングメカニズムを使用してデータセットを小さなチャンク (パーティション) に分割し、クラスターのワーカーノード間で並列に処理できます。パーティション分割は ODP エンティティには適用されないことに注意してください。
詳細については、「[AWS Glue Spark と PySpark のジョブ](https://docs.aws.amazon.com/glue/latest/dg/spark_and_pyspark.html)」を参照してください。
**前提条件**
読み取り元の SAP OData オブジェクト。オブジェクト/EntitySet 名が必要です。例: ` /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder `。
**例**
```
sapodata_read = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder"
}, transformation_ctx=key)
```
## パーティショニングクエリ
### フィールドベースのパーティション分割
Spark で同時実行を使用する場合は、追加の Spark オプション `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、および `NUM_PARTITIONS` を指定できます。これらのパラメータを使用すると、元のクエリは Spark タスクで同時に実行できるサブクエリの `NUM_PARTITIONS` の数に分割されます。整数、日付、および DateTime フィールドは、SAP OData コネクタのフィールドベースのパーティショニングをサポートします。
+ `PARTITION_FIELD`: クエリのパーティション化に使用するフィールドの名前。
+ `LOWER_BOUND`: 選択したパーティションフィールドの包括的な下限値。
データ型が DateTime であるフィールドでは、Spark SQL クエリで使用される Spark タイムスタンプ形式を受け入れます。
有効な値の例: `"2000-01-01T00:00:00.000Z"`
+ `UPPER_BOUND`: 選択したパーティションフィールドの排他的上限値。
+ `NUM_PARTITIONS`: パーティション数。
+ `PARTITION_BY`: 実行するパーティショニングのタイプ。フィールドベースのパーティショニングの場合は、`FIELD` を渡します。
**例**
```
sapodata= glueContext.create_dynamic_frame.from_options(
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet",
"PARTITION_FIELD": "validStartDate"
"LOWER_BOUND": "2000-01-01T00:00:00.000Z"
"UPPER_BOUND": "2020-01-01T00:00:00.000Z"
"NUM_PARTITIONS": "10",
"PARTITION_BY": "FIELD"
}, transformation_ctx=key)
```
### レコードベースのパーティション分割
元のクエリは、元のクエリは Spark タスクで同時に実行できるサブクエリの `NUM_PARTITIONS` の数に分割されます。
レコードベースのパーティショニングは、ODP 以外のエンティティでのみサポートされます。ODP エンティティのページ分割は、次のトークン/スキップトークンを通じてサポートされるためです。
+ `PARTITION_BY`: 実行されるパーティション分割のタイプ。レコードベースのパーティション分割の場合は、`COUNT` が渡されます。
**例**
```
sapodata= glueContext.create_dynamic_frame.from_options(
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet",
"NUM_PARTITIONS": "10",
"PARTITION_BY": "COUNT"
}, transformation_ctx=key)
```
# 制限/コールアウト
+ スキップトークン/デルタトークンでページネーションを行うため、ODP エンティティはレコードベースのパーティション分割と互換性がありません。したがって、レコードベースのパーティション分割の場合、maxConcurrency のデフォルト値は、ユーザー入力に関係なく「null」に設定されます。
+ 制限とパーティション分割の両方が適用された場合、制限はパーティション分割よりも優先されます。
# SAP OData 接続オプション
SAP OData の接続オプションは次のとおりです:
+ `ENTITY_NAME` (文字列) – (必須) 読み取りに使用されます。SAP OData のオブジェクトの名前。
例: /sap/opu/odata/sap/API\$1SALES\$1ORDER\$1SRV/A\$1SalesOrder
+ `API_VERSION`(文字列) - (オプション) 読み取りに使用。使用する SAP OData Rest API バージョン。例: 2.0。
+ `SELECTED_FIELDS`(List) – Default: empty(SELECT \$1). 読み込みに使用されます。オブジェクトに選択する列です。
例: SalesOrder
+ `FILTER_PREDICATE`(文字列) – デフォルト: 空 読み込みに使用されます。Spark SQL 形式である必要があります。
例: `SalesOrder = "10"`
+ `QUERY`(文字列) – デフォルト: 空 読み込みに使用されます。完全な Spark SQL クエリです。
例: `SELECT * FROM /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder`
+ `PARTITION_FIELD`(文字列) - 読み取りに使用されます。クエリをパーティション化するために使用するフィールドです。
例: `ValidStartDate`
+ `LOWER_BOUND`(文字列) - 読み取りに使用されます。選択したパーティションフィールドの包括的な下限値です。
例: `"2000-01-01T00:00:00.000Z"`
+ `UPPER_BOUND`(文字列) - 読み取りに使用されます。選択したパーティションフィールドの排他的上限値です。
例: `"2024-01-01T00:00:00.000Z"`
+ `NUM_PARTITIONS`(整数) – デフォルト: 1。読み込みに使用されます。読み取り用のパーティションの数です。
+ `INSTANCE_URL`(文字列) – SAP インスタンスアプリケーションのホスト URL。
例: `https://example-externaldata.sierra.aws.dev`
+ `SERVICE_PATH`(文字列) – SAP インスタンスアプリケーションサービスパス。
例: `/sap/opu/odata/iwfnd/catalogservice;v=2`
+ `CLIENT_NUMBER`(文字列) – SAP インスタンスアプリケーションのクライアント番号。
例: 100
+ `PORT_NUMBER`(文字列) – デフォルト: SAP インスタンスアプリケーションのポート番号。
例: 443
+ `LOGON_LANGUAGE`(文字列) – SAP インスタンスアプリケーションのログオン言語。
例: `EN`
+ `ENABLE_CDC`(文字列) – CDC を有効にしてジョブを実行するかどうか、つまりトラックの変更でジョブを実行するかどうかを定義します。
例: `True/False`
+ `DELTA_TOKEN`(文字列) – 指定された有効なデルタトークンに基づいて増分データプルを実行します。
例: `D20241107043437_000463000`
+ `PAGE_SIZE` (整数) - レコードをクエリするためのページサイズを定義します。デフォルトのページサイズは 50,000 です。ページサイズを指定すると、SAP はデータセット全体ではなく、API コールごとに定義された数のレコードのみを返します。コネクタは引き続きレコードの合計数を提供し、指定したページサイズを使用してページ分割を処理します。ページサイズを大きくする必要がある場合は、最大 500,000 までの任意の値を選択できます。指定されたページサイズが 500,000 を超えると無視されます。代わりに、システムは許容される最大ページサイズを使用します。希望する値を指定した接続オプション `PAGE_SIZE` を追加することで、AWS Glue Studio UI でページサイズを指定できます。
例: `20000`
# SAP OData エンティティとフィールドの詳細
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/sap-odata-entity-field-details.html)