為對話資料設定存留時間 (TTL)

總覽

在 CX Insights 中設定對話的到期時間有兩種方式：使用 expire_time 欄位或 ttl 欄位。您可以使用 expire_time 欄位設定時間戳記，指出對話的到期時間，也可以使用 ttl 欄位設定對話到期前的時間長度 (以秒為單位)。如果對話同時有 expire_time 和 ttl 值，CX Insights 會使用 expire_time 值。

使用 expire_time 或 ttl 欄位設定的對話會在指定到期時間過後 24 小時刪除。詳情請參閱對話資源說明文件。本頁面說明如何為個別對話和特定專案中的所有對話設定存留時間。

如果對話未設為到期，就會無限期保留在 CX Insights 中，但隨時可手動刪除。

建立具有 TTL 值的對話

以下範例說明如何使用對話資源中的 ttl 欄位，為單一新建立的對話設定 TTL 值。

這項工作需要的權限

如要執行這項工作，您必須具備以下權限：

contactcenterinsights.conversations.create

REST

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：您的 Google Cloud 專案 ID。
TRANSCRIPT_URI：指向含有對話轉錄稿的檔案的 Cloud Storage URI。
MEDIUM：根據資料類型設為 PHONE_CALL 或 CHAT。如未指定，預設值為 PHONE_CALL。
SECONDS：存留時間 (對話到期前的時間)，以秒和秒數分數表示。

HTTP 方法和網址：

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations

JSON 要求主體：

{
  "data_source": {
    "gcs_source": {
      "transcript_uri": "TRANSCRIPT_URI"
    }
  },
  "medium": "MEDIUM",
  "ttl": {
    "seconds": "SECONDS"
  }
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID",
  "dataSource": {
    "gcsSource": {
      "transcriptUri": "gs://cloud-samples-data/ccai/chat_sample.json"
    }
  },
  "createTime": "2021-01-20T10:10:10.123000Z",
  "transcript": {
    "transcriptSegments": [
      ...
      {
        "text": "Thanks for confirming",
        "words": [
          {
            "word": "Thanks"
          },
          {
            "word": "for"
          },
          {
            "word": "confirming"
          }
        ],
        "languageCode": "en-US",
        "channelTag": 2,
        "messageTime": "2021-01-10T10:10:15.123000Z",
        "segmentParticipant": {
          "role": "HUMAN_AGENT",
          "userId": "555"
        }
      },
      ...
    ]
  },
  "medium": "CHAT",
  "duration": "5.00s",
  "turnCount": 10,
  "startTime": "2021-01-10T10:10:10.123000Z"
  "expireTime":"2021-01-21T10:10:10.123000Z",
}

Python

如要向 CX Insights 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

from google.cloud import contact_center_insights_v1
from google.protobuf import duration_pb2


def create_conversation_with_ttl(
    project_id: str,
    transcript_uri: str = "gs://cloud-samples-data/ccai/chat_sample.json",
    audio_uri: str = "gs://cloud-samples-data/ccai/voice_6912.txt",
) -> contact_center_insights_v1.Conversation:
    """Creates a conversation with a TTL value.

    Args:
        project_id:
            The project identifier. For example, 'my-project'.
        transcript_uri:
            The Cloud Storage URI that points to a file that contains the
            conversation transcript. Format is 'gs://{bucket_name}/{file.json}'.
            For example, 'gs://cloud-samples-data/ccai/chat_sample.json'.
        audio_uri:
            The Cloud Storage URI that points to a file that contains the
            conversation audio. Format is 'gs://{bucket_name}/{file.json}'.
            For example, 'gs://cloud-samples-data/ccai/voice_6912.txt'.

    Returns:
        A conversation.
    """
    # Construct a parent resource.
    parent = (
        contact_center_insights_v1.ContactCenterInsightsClient.common_location_path(
            project_id, "us-central1"
        )
    )

    # Construct a conversation.
    conversation = contact_center_insights_v1.Conversation()
    conversation.data_source.gcs_source.transcript_uri = transcript_uri
    conversation.data_source.gcs_source.audio_uri = audio_uri
    conversation.medium = contact_center_insights_v1.Conversation.Medium.CHAT

    # Construct a TTL.
    ttl = duration_pb2.Duration()
    ttl.seconds = 86400
    conversation.ttl = ttl

    # Call the Insights client to create a conversation.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    conversation = insights_client.create_conversation(
        parent=parent, conversation=conversation
    )

    print(f"Created {conversation.name}")
    return conversation

Java

如要向 CX Insights 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import com.google.cloud.contactcenterinsights.v1.Conversation;
import com.google.cloud.contactcenterinsights.v1.ConversationDataSource;
import com.google.cloud.contactcenterinsights.v1.CreateConversationRequest;
import com.google.cloud.contactcenterinsights.v1.GcsSource;
import com.google.cloud.contactcenterinsights.v1.LocationName;
import com.google.protobuf.Duration;
import java.io.IOException;

public class CreateConversationWithTtl {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my_project_id";
    String transcriptUri = "gs://cloud-samples-data/ccai/chat_sample.json";
    String audioUri = "gs://cloud-samples-data/ccai/voice_6912.txt";

    createConversationWithTtl(projectId, transcriptUri, audioUri);
  }

  public static Conversation createConversationWithTtl(
      String projectId, String transcriptUri, String audioUri) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct a parent resource.
      LocationName parent = LocationName.of(projectId, "us-central1");

      // Construct a conversation.
      Conversation conversation =
          Conversation.newBuilder()
              .setDataSource(
                  ConversationDataSource.newBuilder()
                      .setGcsSource(
                          GcsSource.newBuilder()
                              .setTranscriptUri(transcriptUri)
                              .setAudioUri(audioUri)
                              .build())
                      .build())
              .setMedium(Conversation.Medium.CHAT)
              .setTtl(Duration.newBuilder().setSeconds(86400).build())
              .build();

      // Construct a request.
      CreateConversationRequest request =
          CreateConversationRequest.newBuilder()
              .setParent(parent.toString())
              .setConversation(conversation)
              .build();

      // Call the Insights client to create a conversation.
      Conversation response = client.createConversation(request);
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

如要向 CX Insights 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my_project_id';
// const transcriptUri = 'gs://cloud-samples-data/ccai/chat_sample.json';
// const audioUri = 'gs://cloud-samples-data/ccai/voice_6912.txt';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createConversationWithTtl() {
  const [conversation] = await client.createConversation({
    parent: client.locationPath(projectId, 'us-central1'),
    conversation: {
      dataSource: {
        gcsSource: {
          transcriptUri: transcriptUri,
          audioUri: audioUri,
        },
      },
      medium: 'CHAT',
      ttl: {
        seconds: 86400,
      },
    },
  });
  console.info(`Created ${conversation.name}`);
}
createConversationWithTtl();

為所有來電對話設定專案層級的存留時間

下列程式碼範例示範如何使用設定資源中的 conversation_ttl 欄位，設定專案層級的 TTL。如果沒有指定個別的到期時間或其他存留時間值，所有傳入的對話都會套用這個存留時間。

這項工作需要的權限

如要執行這項工作，您必須具備以下權限：

contactcenterinsights.settings.update

REST

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：您的 Google Cloud 專案 ID。
SECONDS：存留時間 (對話到期前的時間)，以秒和秒數分數表示。

HTTP 方法和網址：

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/settings?updateMask=conversation_ttl

JSON 要求主體：

{
  "conversation_ttl": {
    "seconds": "SECONDS"
  }
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/settings?updateMask=conversation_ttl"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/settings?updateMask=conversation_ttl" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/$PROJECT/locations/us-central1/settings",
  "createTime": "2021-01-20T10:10:10.123000Z",
  "updateTime": "2021-01-20T11:11:11.456000Z",
  "conversationTtl": "86400s"
}

Python

如要向 CX Insights 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

from google.api_core import protobuf_helpers
from google.cloud import contact_center_insights_v1
from google.protobuf import duration_pb2


def set_project_ttl(project_id: str) -> None:
    """Sets a project-level TTL for all incoming conversations.

    Args:
        project_id:
            The project identifier. For example, 'my-project'.

    Returns:
        None.
    """
    # Construct a settings resource.
    settings = contact_center_insights_v1.Settings()
    settings.name = (
        contact_center_insights_v1.ContactCenterInsightsClient.settings_path(
            project_id, "us-central1"
        )
    )

    conversation_ttl = duration_pb2.Duration()
    conversation_ttl.seconds = 86400
    settings.conversation_ttl = conversation_ttl

    # Construct an update mask to only update the fields that are set on the settings resource.
    update_mask = protobuf_helpers.field_mask(None, type(settings).pb(settings))

    # Construct an Insights client that will authenticate via Application Default Credentials.
    # See authentication details at https://cloud.google.com/docs/authentication/production.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()

    # Call the Insights client to set a project-level TTL.
    insights_client.update_settings(settings=settings, update_mask=update_mask)

    # Call the Insights client to get the project-level TTL to confirm that it was set.
    new_conversation_ttl = insights_client.get_settings(
        name=settings.name
    ).conversation_ttl
    print(
        "Set TTL for all incoming conversations to {} day".format(
            new_conversation_ttl.days
        )
    )

Java

如要向 CX Insights 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import com.google.cloud.contactcenterinsights.v1.Settings;
import com.google.cloud.contactcenterinsights.v1.SettingsName;
import com.google.protobuf.Duration;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class SetProjectTtl {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace this variable before running the sample.
    String projectId = "my_project_id";

    setProjectTtl(projectId);
  }

  public static void setProjectTtl(String projectId) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct a settings resource.
      SettingsName name = SettingsName.of(projectId, "us-central1");
      Settings settings =
          Settings.newBuilder()
              .setName(name.toString())
              .setConversationTtl(Duration.newBuilder().setSeconds(86400).build())
              .build();

      // Construct an update mask.
      FieldMask updateMask = FieldMask.newBuilder().addPaths("conversation_ttl").build();

      // Call the Insights client to set a project-level TTL.
      Settings response = client.updateSettings(settings, updateMask);
      System.out.printf("Set TTL for all incoming conversations to 1 day");
    }
  }
}

Node.js

如要向 CX Insights 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const projectId = 'my_project_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function setProjectTtl() {
  await client.updateSettings({
    settings: {
      name: client.settingsPath(projectId, 'us-central1'),
      conversationTtl: {
        seconds: 86400,
      },
    },
    updateMask: {
      paths: ['conversation_ttl'],
    },
  });
  console.info('Set TTL for all incoming conversations to 1 day');
}
setProjectTtl();

為對話資料設定存留時間 (TTL) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

建立具有 TTL 值的對話

這項工作需要的權限

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Java

Node.js

為所有來電對話設定專案層級的存留時間

這項工作需要的權限

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Java

Node.js

為對話資料設定存留時間 (TTL)