ディクショナリの操作

ディクショナリは、データをキーと値のペアとして保存するできるコンテナの一種であり、単一のバージョンに添付することなく、サービス内で使用することができます。ディクショナリは、ディクショナリコンテナとディクショナリ項目で構成されています。ディクショナリ項目を使用して、キーと値のペアを作成し保存します。そのディクショナリ項目は、ディクショナリコンテナに追加されます。ディクショナリコンテナはサービスバージョンにアタッチされますが、サービスのバージョンを増分することなく、作成後いつでも更新することができます。

コントロールパネル、カスタム VCL スニペット、Fastly API を使用して、ディクショナリを操作することができます。また、プライベートディクショナリを作成することもできます。

設定前の注意点

ディクショナリを操作する前に、Dictionaries についてガイドをご参照ください。また、ディクショナリの仕組み、一般的なユースケース、ディクショナリの使用の制約についてご理解ください。

Dictionaries ページ経由でディクショナリを操作する

Dictionaries ページを使用して、ディクショナリを作成および操作することができます。

Dictionaries ページを使用して作成されたディクショナリを表示する

Dictionaries ページ経由でディクショナリを表示するには、ご利用のサービスのディクショナリ管理エリアに移動します。

1. Fastly コントロールパネルにログインします。
2. Home ページから、適切なサービスを選択します。検索ボックスで ID、名称、ドメインによる検索が行えます。
3. Edit configuration をクリックし、アクティブなバージョンをクローンするオプションを選択します。
4. Data の下にある Dictionaries をクリックします。 現在選択されているサービスバージョンに関連する既存のディクショナリがある場合は、そのディクショナリが表示されます。

Dictionaries ページから検索バーを使用して、ディクショナリのリストをフィルターできます。任意のディクショナリカードの検索バーを使用して、ディクショナリ内のキーまたは値をフィルターできます。

Dictionaries ページ経由でディクショナリを作成する

Dictionaries ページ経由でディクショナリを作成するには、ディクショナリコンテナを作成し、その中に存在するアイテムを作成する必要があります。

ディクショナリコンテナの作成

まず、以下の手順に従ってディクショナリコンテナを作成します。

1. Fastly コントロールパネルにログインします。
2. Home ページから、適切なサービスを選択します。検索ボックスで ID、名称、ドメインによる検索が行えます。
3. Edit configuration をクリックし、アクティブなバージョンをクローンするオプションを選択します。
4. Data の下にある Dictionaries をクリックします。
5. Create a dictionary をクリックします。
6. Name of dictionary フィールドに、ディクショナリ用に分かりやすい名前を入力します (例: Example Dictionary)。
7. Add をクリックします。
8. Activate をクリックすると、編集中のサービスバージョンに設定変更が反映されます。

ディクショナリ項目の作成

ディクショナリコンテナを作成した後、それに項目を追加します。

1. Add item をクリックします。

2. Key フィールドには、データの一部の項目を表す一意の識別子を入力します (例: example.com)。

3. Value フィールドには、一意の識別子に関連する値を入力します (例: yes)。

4. Add をクリックします。キーと値のペアがディクショナリコンテナに表示されます。追加された項目は直ちに有効となります。

   

ディクショナリを使用する

ディクショナリを作成したら、すぐに使用を開始できます。ディクショナリを使用するには、ヘッダーを作成して追加する必要があります。以下の手順に従ってください。

1. Fastly コントロールパネルにログインします。
2. Home ページから、適切なサービスを選択します。検索ボックスで ID、名称、ドメインによる検索が行えます。
3. Edit configuration をクリックし、アクティブなバージョンをクローンするオプションを選択します。
4. Content をクリックします。

5. Create header をクリックします。

   

6. 以下の要領で、Create a header ページの各フィールドに入力します。

   • Name フィールドには、ヘッダールール名を入力します (例: Redirect lookup)。
   • Type メニューから Request を選択し、Action メニューから Set を選択します。
   • Destination フィールドに、選択したアクションの影響を受けるヘッダーの名前を入力します (例: url)。
   • Source フィールドには、ヘッダーのコンテンツを取得する場所を入力します (例: table.lookup(redirects, req.url))。
   • Ignore if set メニューから No を選択します。
   • Priority フィールドはそのままにしておきます。

7. Create をクリックしてヘッダーを作成します。Content ページに新しいヘッダーが表示されます。

ヘッダーを作成したら、条件を作成して、ディクショナリを使用する条件を指定できます。

1. 作成した新規ヘッダーの横にある Attach a condition をクリックします。

2. Create a new request condition をクリックします。

   

3. Name フィールドに条件の名前を入力します (例: My dictionary condition)。

4. Apply if フィールドに条件を入力します (例: table.lookup(redirects, req.url))。

5. Save and apply to をクリックします。

6. Activate をクリックして設定への変更をデプロイします。

Dictionaries ページ経由でコンテナを編集する

ロックされていない任意のサービスバージョンで、Dictionaries ページを介して作成されたディクショナリコンテナの名前を編集できます。

1. ご利用のサービスのロックされていないバージョンに関連するディクショナリを検索します。
2. ディクショナリコンテナ名の横にある鉛筆 をクリックします。
3. 名前を変更し、Save をクリックします。

Dictionaries ページ経由でアイテムを編集する

コンテナ内のディクショナリ項目は、いつでも編集することができます。Dictionaries ページで作成したディクショナリコンテナのキーと値のペアを編集するには、以下の指示に従ってください。

1. キーと値のペアが表示される、サービスに関連付けられているディクショナリを探します。ディクショナリ項目はバージョン管理されていないため、選択したサービスのバージョンは関係ありません。お客様にとって最も合理的なものをお選びください。
2. ディクショナリ項目の上にカーソルを合わせて、表示される鉛筆 をクリックします。
3. 必要に応じてキーや値を編集します。
4. Save をクリックします。変更した内容は、すぐに設定に反映されます。ディクショナリコンテナがすでに有効化されているサービスバージョンと関連付けられている場合、それらの変更は直ちに本番環境に反映されます。

Dictionaries ページ経由でディクショナリを削除する

ディクショナリの制約事項を考慮しながら、VCL スニペットやディクショナリコンテナを使用してディクショナリを削除したり、ディクショナリ内の項目を Dictionaries ページで削除することができます。

ディクショナリコンテナの削除

ロックされていないサービスバージョンの Dictionaries ページで作成されたディクショナリコンテナを削除することができます。

1. ご利用のサービスのロックされていないバージョンに関連するディクショナリを検索します。
2. ディクショナリの右上にあるゴミ箱 をクリックします。
3. Confirm and Delete をクリックします。
4. Activate をクリックすると、編集中のサービスバージョンに設定変更が反映されます。

ディクショナリ項目の削除

コンテナ内のディクショナリ項目は、いつでも削除することができます。Dictionaries ページで作成したディクショナリコンテナに含まれるキーと値のペアを削除するには、以下の指示に従ってください。

1. キーと値のペアが表示される、サービスに関連付けられているディクショナリを探します。ディクショナリ項目はバージョン管理されていないため、選択したサービスのバージョンは関係ありません。お客様にとって最も合理的なものをお選びください。
2. 辞書項目の上にカーソルを合わせて、表示されるゴミ箱 をクリックします。
3. Confirm and Delete をクリックします。

VCL スニペットを使用したディクショナリの設定

カスタム VCL スニペットを使用して、ディクショナリを作成して操作することができます。カスタム VCL で作成されたディクショナリは、API または Dictionaries ページを使用して操作することができません。カスタム VCL を使用して作成されたディクショナリコンテナは、必ずカスタム VCL で操作する必要があります。カスタム VCL 経由でアップロードされたディクショナリは、バージョンレスではありません。

VCL スニペットで作成したディクショナリを表示する

VCL Snippets リンクでディクショナリを表示するには、以下の手順に従ってください。

1. Fastly コントロールパネルにログインします。
2. Home ページから、適切なサービスを選択します。検索ボックスで ID、名称、ドメインによる検索が行えます。
3. Edit configuration をクリックし、アクティブなバージョンをクローンするオプションを選択します。
4. VCL Snippets をクリックします。
5. ディクショナリのコンテンツを表示するには、View source をクリックします。

VCL スニペットを使用してディクショナリを作成する

VCL スニペットを使用してディクショナリを作成するには、以下の手順に従ってください。

1. Fastly コントロールパネルにログインします。
2. Home ページから、適切なサービスを選択します。検索ボックスで ID、名称、ドメインによる検索が行えます。
3. Edit configuration をクリックし、アクティブなバージョンをクローンするオプションを選択します。

4. VCL snippets をクリックします。

5. Create Snippet をクリックします。

   

6. Name フィールドに、適切な名前 (例: Example Dictionary) を入力します。

7. Type (placement of the snippet) から、init を選択します。

8. VCL フィールドではテーブルを作成し、キーと値のペアを追加します。例えば、ある URL を別のパスにリダイレクトするテーブルを作成したいとします。

   1
   2
   3
   4

   table redirects {
     "/source1": "/dest1",
     "/source2": "/dest2"
   }

   テーブルは、コードで参照できるキーと値のペアのセットです。このテーブルの中身を別のキーと値のペアに置き換えることができます。

9. Create をクリックしてスニペットを作成します。

VCL スニペットでディクショナリを使用する

ディクショナリを作成したら、すぐに使用を開始できます。

VCL スニペットでディクショナリを使用するには、以下の手順に従ってください。

1. Fastly コントロールパネルにログインします。
2. Home ページから、適切なサービスを選択します。検索ボックスで ID、名称、ドメインによる検索が行えます。
3. Edit configuration をクリックし、アクティブなバージョンをクローンするオプションを選択します。

4. VCL snippets をクリックします。

5. Create Snippet をクリックします。

   

6. 以下の要領で、Create a VCL snippet の各フィールドに入力します。

   • Name フィールドに、適切な名前 (例: URL redirect) を入力します。
   • Type (placement of the snippet) のセクションで、within subroutine を選択します。
   • Select subroutine メニューから、recv (vcl_recv) を選択します。
   • VCL フィールドには、VCL スニペットを使用してディクショナリを作成した際に作ったテーブルを使用する条件を追加します。例えば、URL の宛先を書き換える必要がある場合、以下のようになります。

   1
   2
   3

   if (table.lookup(redirects, req.url)) {
      set req.url = table.lookup(redirects, req.url);
   }

   ここで、table.lookup は必要なコンテンツをディクショナリでチェックします。最初のパラメーターは検索対象のテーブル、2番目のパラメーターは検索対象のキーです。キーが2番目のパラメーターと完全に一致する場合は、その値が返されます。ディクショナリ検索では regex は機能しないのでご注意ください。

7. Create をクリックしてスニペットを作成します。

8. Activate をクリックして設定への変更をデプロイします。

VCL スニペットを使用してディクショナリを編集する

ロックされていない任意のサービスバージョンで、ディクショナリの名前と、VCL スニペットを使用して作成された条件を編集することができます。

1. ご利用のサービスのロックされていないバージョンに関連するディクショナリを検索します。
2. 辞書の横にある鉛筆 をクリックします。 これで、名前や条件を変更できます。
3. 変更が完了したら、Update をクリックします。
4. Activate をクリックすると、編集したバージョンが有効になり、VCL の変更内容が表示されます。

VCL スニペットを使用してディクショナリを削除する

以下の手順に従って VCL スニペットを使用してディクショナリを削除することができます。ディクショナリの削除に伴う制約事項に注意してください。

1. ご利用のサービスのロックされていないバージョンに関連するディクショナリを検索します。
2. スニペットの右上にあるゴミ箱 をクリックします。
3. Confirm and Delete をクリックします。
4. Activate をクリックすると、編集中のサービスバージョンに設定変更が反映されます。

プライベートディクショナリ

プライベートディクショナリには、Fastly コントロールパネルまたは API ではリスト表示や読み込みができないディクショナリ項目が格納されます。

制約と考慮事項

プライベートディクショナリを作成する際には、以下の点に留意してください。

• プライベートディクショナリの作成、読み取り、更新、削除が可能です。プライベートディクショナリは API 経由でのみ作成することができます。
• 作成後、辞書の write_only 属性を更新することはできません。
• プライベートディクショナリに属する項目の作成、更新、削除が可能です。サービスバージョンを有効にした後は、既存のプライベートディクショナリ項目の値の更新は、API 経由でのみ可能です。Fastly コントロールパネルまたは API を使用して、新しい項目をプライベートディクショナリに追加することができます。
• プライベートディクショナリに属する項目を API で確認することはできません。サービスバージョンを有効化した後は、Fastly のコントロールパネルを使用してプライベートディクショナリに属する項目を表示することはできません。
• サービスの設定によっては、プライベートディクショナリに格納されているデータをヘッダーで送信したり、ログストリーミングのエンドポイントに送信することができます。

プライベート・ディクショナリ・コンテナの作成

プライベート・ディクショナリ・コンテナを使用するには、まずロックされていないバージョンのサービス内に空のディクショナリコンテナを作成します。

プライベートディクショナリを使用する前に、そのプライベート・ディクショナリ・コンテナが、ロックも有効化もされていないサービスバージョンの少なくとも1つと関連付けられ、そのサービスがプライベートディクショナリの存在を認識できるようにする必要があります。

例えば、API 経由で my_example_dictionary のプライベートディクショナリを作成する場合、以下のコマンドを実行して API コールを行います。

$ curl -X POST -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'name=my_example_dictionary&write_only=true' https://api.fastly.com/service/<service_id>/version/<version_number>/dictionary

これにより以下が返されます。

1
2
3
4
5
6
7
8
9
10

{
  "created_at": "2017-05-03T16:11:41+00:00",
  "deleted_at": null,
  "id": "<dictionary_id>",
  "name": "my_example_dictionary",
  "service_id": "<service_id>",
  "updated_at": "2017-05-03T16:11:41+00:00",
  "version": <version_number>,
  "write_only": true
}

ディクショナリの作成後、ディクショナリ項目を追加できます。作業終了後、サービスの有効化を忘れずに行ってください。

VCL でプライベートディクショナリを確認する

プライベートディクショナリのコンテンツは VCL で非表示になっています。プライベートディクショナリのメタデータが以下のように表示されます。

1
2
3
4
5
6

table my_example_dictionary {
     # REDACTED dictionary content
     # last_updated: 2017-10-16 20:44:43
     # item_count: 2
     # digest: 8f92141234567890da30ba9cea7d98ef614
 }

次のステップ

Developer Hub でディクショナリの使用についてのカスタム VCL の例を参照してください。