パートナーAPI

ファイルプロトコルを介したデータの同期

このセクションでは、CitrusAdがサポートしているプロトコルの概要と、CitrusAdがサーバーから自動的にデータファイルをダウンロードできるようにするためのファイル名の付け方について説明します。

プロトコル

CitrusAdがサポートしているデータファイルの取得方法は、いくつかあります。データファイルはサーバー上に保存し、標準プロトコルのいずれかを介してダウンロードされるようにする必要があります。

現在、CitrusAdは以下のプロトコル経由でのデータファイルのダウンロードをサポートしています。

  • GCS
  • SFTP
  • SCP
  • HTTPS

通常、CitrusAdにてファイルをダウンロードできるようにするためには、データファイルのプロトコル、ホスト、ポート、ファイルパスに関する情報を提供していただく必要があります。データファイルのダウンロードで認証が必要な場合、CitrusAdにその認証情報（ユーザー名やパスワードなど）を提供して、お客様のシステムにて認証されるようにする必要があります。

SFTPプロトコルを使用する場合、CitrusAdでは、データファイルのダウンロード用に以下の2種類の認証をサポートしています。

  • ユーザー名とパスワード
  • CitrusAdの公開鍵

公開鍵を使用して認証する場合、SFTPサーバーに以下の公開鍵をインストールする必要があります。

ステージング：

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDMd4w5Z6hsjlUc0/r3dTJ+IaM9Mm+l3ZTrX3D5+30ZNiAb3Mhvlp8gv37CFKzqM90oFejl15bbr5dymjycsOWInxqkMyLOTbdMFAk7hmicNvN5bt3tx/Z0UewNvAx0Uw9Qxu7SCMSAalk9l7dqLp5RFFj+RHq9ApV8KIA/Fw2mjCw2vrJhiRWeuUuNNQTbGFBA5y72ATeYA2p0ZK3/TTJxyxCL70zGVxFG0jdAurfXKujYaF73Ql/gl5wmtnxGvTORtvObQdc2jCTsynj1w17LSZAdeoPQGnQkVCk37ZUnWTw8s4RYjHFVunsTDxJO5Qnw5yj8oqhe5IdpQyavUj+otRd6900q/3dK60IELH6AFz+ZEqudlBh8ZO2hvHIDS2Ii5S3LunlejykAVdRl7RVHA17Pk3mmrHCS6i3n9ZliBYeVQiKme2jHVB+ESrHFxQWl3ct9MYFNlAqwuhTFQRSG9ioSEHX5Dnmqk8aqbm/4pYY4b7YHOcIpHrtrVrFTJ3vLM1If1OVrDQidFhi1ArmoCU+PO65jNSeMj27m/HoX7Mbcmi8F++Op3MgP8iJrohE0Wjz+use7nlDtQTtDxDeEQQYGqsz4DOtH/jn1TWRynaXZqwPqC5Q6b52QM22T+E3rgT/4G7yJU3IRKioByOck251MEtOEgSCvvIAaV685fQ==

本番

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCtpIUFoYu8OUesZGP9rffv6/hky1HbQCAhC8hNRmcWpdptzRYsKIZFPz9t2vb85dierTZqJstAEJkePHd25cZ8btIBacbAR49avCIXiBuVgvlJk1+Er2dyYqSzSeFhpzlZxi4CkGo/Nsx7yxPi5693fdVF3vr+/iencw1tdLJJXfT6j1YLBCREg+IziBCO6m9P0QQGEDXYvsOmIzl0CJ8enU7gjvnYL5ify1/aGpoXv9/XcCYJWXTQmvmISknOMdC4pBiuDqsE9CX27FLQQb1ZT5jNrqD5hFsEo0rWqLiCbb5qoxIdMSe/IbA+sewgpgTPNJXeCNLSSH/MHhj2IgiMZGDDDaVaqMZD7N2jeQdI6SQbgvXiLTTUL4gNyO5eN9oqoeJumeZMi0+MQ7kkfHDYGtKe3RMxL7heL650HL+eWDIybezyPdQmfyVew9KuN0uB+2X+2NxQs8ZLqow486XDfUDfo+rPuoIvkYy7Z8ox+gne+1iAk43TCekcDwxlc56R9muMtGLuzzg1x9s9MqsAg5JNWEPQ8giAwCQJwm7h3UcCY3TJCn0LUzYHc7Ycr11JfIXL47vYGH3C0XBYlbEU/8m4VhhexzgJi8G/reclY5pfjtwQGOiobsxLsWgGx6Qoz/qWqmGwQIg+qi7jvA7jnltUP+RTFZpmd18/dSxB+w==

本番：

データの圧縮と暗号化

同期のためデータをサーバーにアップロードする前に、データを圧縮して暗号化する必要がある場合があります。データファイルが圧縮され、かつ暗号化されている場合、CitrusAdは、そのデータファイルは圧縮されてから暗号化されているとみなします。

データファイルが暗号化されている場合、CitrusAdはそのデータファイルをダウンロードした後に、これを複合化します。現在は、PGPプログラムによって暗号化されたファイルのデータ復号化に対応しています。PGP暗号の詳細については、https://tools.ietf.org/html/rfc4880をご覧ください。

データファイルにこのタイプの暗号化手法を使用する場合は、以下の公開鍵を用いてデータファイルを暗号化し、サーバーにアップロードしてください。暗号化されたデータファイルを復号化できるのは、CitrusAdだけです。

公開鍵

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
tPA=
=lRkN
-----END PGP PUBLIC KEY BLOCK-----

データファイルが圧縮されて納品された場合、処理前にデータファイルを解凍します。現在、2種類の圧縮形式（zipとgzip）の解凍に対応しています。

ファイルの命名規則

前述のとおり、CitrusAdにてデータファイルをダウンロードして処理するためには、データファイルのプロトコル、ホスト、ポート、およびファイルパスに関する情報を提供していただく必要があります。都合の良い時間を選んで毎日サーバーにデータファイルが入るようにしていただければ、CitrusAdにて毎日そのデータファイルをダウンロードします。

CitrusAdが毎日ダウンロードするターゲットファイルを指定する最も簡単な方法は、ファイル名を明示的に指定することです。CitrusAdはそのファイル名を使って、お客様のサーバーからデータファイルを取得します。

お客様のサーバーとCitrusAdの間の通信方式として、FTP、FTPS、SFTPプロトコルを使用する場合、CitrusAdがダウンロードする対象ファイルを指定するために、以下の他のオプションもサポートしています。

  • Rolling_earliest
  • Rolling_earliest_24_hours
  • Rolling_latest
  • Rolling_latest_24_hours.

これらはターゲットファイルモードとも呼ばれます。

上記のいずれかのオプションを選択した場合、CitrusAdにそのデータファイル名のテキストテンプレートを提供する必要があります。テキスト形式のテンプレートでは、「{*}」という特殊な文字列があります。CitrusAdは、お客様から提供されたテンプレートを使用して、お客様のサーバー上のファイル名と照合し、毎日、ターゲットファイルを選択してダウンロードします。

テンプレートの例は、「CitrusAdCatalogDataAU{}.txt」です。テンプレートは、一致するファイル名がプレフィックス「CitrusAdCatalogData_AU」で始まり、サフィックス「.txt」で終わる必要があることを定義しています。テンプレート「CitrusAdCatalogDataAU{_}.txt」を使用すると、以下のファイル名がテンプレートと一致します。

CitrusAdCatalogProduct_AU_20190315.txt
CitrusAdCatalogProduct_AU_20190314.txt
CitrusAdCatalogProduct_AU_20190312.txt

お客様がアップロードしているデータファイルをダウンロードしないようにするため、CitrusAdでは、サーバーにアクセスした時点から1分以上経過したデータファイルのみをダウンロードするようにしています。

テンプレートに一致するファイル名は複数ありますが、CitrusAdは一度に1つのファイルのみをダウンロードし、処理します。候補のリストからファイルを選択するため、CitrusAdではさまざまなターゲットファイルモードを定義しており、お客様に選択していただけるようにしています。ターゲットファイルモードについては、以下で詳しく説明します。

Rolling_earliest

このターゲットファイルモードでは、テンプレートを使ってファイル名で絞り込み、ファイル名の昇順で結果をソートして最初の結果を返します。

例えば、ファイル名のテンプレートが「CitrusAdCatalogDataAU{*}.txt」で、テンプレートで絞り込んだファイル名のリストが以下のような場合、このターゲットファイルモードでは「CitrusAdCatalogProduct_AU_20190312.txt」が選ばれてダウンロードされます。

CitrusAdCatalogProduct_AU_20190312.txt
CitrusAdCatalogProduct_AU_20190313.txt
CitrusAdCatalogProduct_AU_20190314.txt

Rolling_earliest_24_hours

このターゲットファイルモードでは、まずテンプレートを使って、ファイル名でフィルタリングを行います。そのうえで、直近24時間以内に変更されたファイルのみを選択します。最後に、ファイル名の昇順で結果をソートし、最初の結果を返します。

例えば、現在時刻が「2019-03-15 10:30:07」、ファイル名のテンプレートが「CitrusAdCatalogDataAU{*}.txt」であるとします。テンプレートでフィルタリングされるファイル名のリストが下の表の場合、このターゲットファイルモードでダウンロードするファイルとして、「CitrusAdCatalogProduct_AU_20190314.txt」が選ばれます。

ファイル名と最終更新日時の情報を持つファイルの例

ファイル名最終更新日
CitrusAdCatalogProduct_AU_20190312.txt2019年3月13日15:35:11
CitrusAdCatalogProduct_AU_20190313.txt2019年3月13日 15:35:08
CitrusAdCatalogProduct_AU_20190314.txt2019年3月14日 15:35:10
CitrusAdCatalogProduct_AU_20190315.txt2019年3月15日 10:05:07

Rolling_latest

このターゲットファイルモードでは、テンプレートを使って、ファイル名でフィルタリングを行います。そのうえで、ファイル名の降順で結果をソートし、最初の結果を返します。

例えば、ファイル名のテンプレートが「CitrusAdCatalogDataAU{*}.txt」で、テンプレートで絞り込んだファイル名のリストが以下のような場合、このターゲットファイルモードでは「CitrusAdCatalogProduct_AU_20190314.txt」が選ばれてダウンロードされます。

CitrusAdCatalogProduct_AU_20190314.txt
CitrusAdCatalogProduct_AU_20190313.txt
CitrusAdCatalogProduct_AU_20190312.txt

このターゲットファイルモードは、Rolling_earliestと同様です。ただし、ファイル名の昇順ではなく、ファイル名の降順でソートしています。

Rolling_latest_24_hours

このターゲットファイルモードでは、まずテンプレートを使って、ファイル名でフィルタリングを行います。そのうえで、直近24時間以内に変更されたファイルのみを選択します。最後に、ファイル名の降順で結果をソートし、最初の結果を返します。

例えば、現在時刻が「2019-03-15 10:30:07」、ファイル名のテンプレートが「CitrusAdCatalogDataAU{*}.txt」であるとします。テンプレートでフィルタリングされるファイル名のリストが下の表の場合、このターゲットファイルモードでダウンロードするファイルとして、「CitrusAdCatalogProduct_AU_20190315.txt」が選ばれます。

このターゲットファイルモードは、Rolling_earliest_24_hoursと同様です。ただし、ファイル名の昇順ではなく、ファイル名の降順でソートしています。

ファイル名と最終更新日時の情報を持つファイルの例

ファイル名最終更新日
CitrusAdCatalogProduct_AU_20190312.txt2019年3月13日15:35:11
CitrusAdCatalogProduct_AU_20190313.txt2019年3月13日 15:35:08
CitrusAdCatalogProduct_AU_20190314.txt2019年3月14日 15:35:10
CitrusAdCatalogProduct_AU_20190315.txt2019年3月15日 10:05:07