PublishMessage 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

PublishMessage 정책은 Apigee 및 Apigee Hybrid 버전 1.7 이상에서 사용 가능합니다.

개요

PublishMessage 정책을 사용하면 API 프록시 흐름 정보를 Google Cloud Pub/Sub 주제에 게시할 수 있습니다. Google의 Pub/Sub를 사용하면 서비스가 훨씬 더 짧은 지연 시간으로 비동기 통신을 할 수 있도록 해줍니다. Pub/Sub에 대한 자세한 내용은 Pub/Sub란 무엇인가요?를 참조하세요. Pub/Sub 주제에 게시할 정보는 리터럴 텍스트 또는 흐름 변수일 수 있습니다. 메시지 템플릿을 사용하여 리터럴 텍스트와 흐름 변수의 조합을 지정할 수도 있습니다.

게시 요청이 성공하면 Apigee는 publishmessage.message.id 흐름 변수를 Pub/Sub 서버에서 반환된 값으로 설정합니다. 자세한 내용은 흐름 변수를 참조하세요.

이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 모든 사용자가 정책 및 환경 유형에 대해 알아야 할 필요는 없습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.

참고:

• PublishMessage 정책을 사용하여 하나의 주제에만 메시지를 게시할 수 있습니다. 여러 주제에 메시지를 게시하려면 여러 PublishMessage 정책(주제당 하나의 정책)을 사용합니다.
• PublishMessage 정책을 실행하려면 Google Cloud 프로젝트에 Pub/Sub API를 사용 설정해야 합니다. Google Cloud 프로젝트에 API를 사용 설정하는 방법에 대한 자세한 내용은 서비스 사용 설정 및 중지를 참조하세요.

인증 및 프록시 배포

PublishMessage 정책을 실행하려면 인증 토큰이 필요합니다. 그러나 정책 정의에는 명시적 <Authentication> 요소가 없습니다. Google 인증을 사용하려면 API 프록시를 배포해야 합니다. 그러면 내부적으로 인증 토큰이 요청에 추가됩니다. Google 인증을 사용하는 API 프록시를 배포하는 방법에 대한 자세한 내용은 배포 단계를 참조하세요. API 프록시에서 Google 인증을 사용하는 것 외에도 pubsub.topics.publish 권한을 가진 역할이 있는 서비스 계정으로 API 프록시를 배포해야 합니다. Pub/Sub의 Identity and Access Management(IAM) 역할에 대한 자세한 내용은 권한 및 역할을 참조하세요.

<PublishMessage>

PublishMessage 정책을 지정합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	해당 사항 없음
하위 요소	<CloudPubSub> <DisplayName> <Source>

다음 표에서는 <PublishMessage>의 하위 요소를 간략하게 설명합니다.

하위 요소	필수 여부	설명
<CloudPubSub>	필수	<Topic>의 상위 요소입니다. <Topic> 요소는 메시지를 게시하려는 Pub/Sub 주제를 지정합니다.
<DisplayName>	선택사항	정책의 커스텀 이름입니다.
<IgnoreUnresolvedVariables>	선택사항	Apigee가 해결되지 않은 변수를 발견하면 처리를 중지할지 여부를 지정합니다.
<Source>	필수	게시할 메시지를 지정합니다.
기타 하위 요소
<Topic>	필수	메시지를 게시하려는 Pub/Sub 주제를 지정합니다.

<PublishMessage> 요소는 다음 구문을 사용합니다.

구문

<?xml version="1.0" encoding="UTF-8"?><PublishMessage continueOnError="[true|false]" enabled="[true|false]" name="Publish-Message-1">
    <DisplayName>DISPLAY_NAME</DisplayName>
    <Source>SOURCE_VALUE</Source>
    <CloudPubSub>
        <Topic>TOPIC_NAME</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PublishMessage>

예시

다음 예시에서는 <PublishMessage> 정책 정의를 보여줍니다.

<?xml version="1.0" encoding="UTF-8"?><PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>{flow-variable-1}</Source>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성	기본	필수 여부	설명
name	해당 없음	필수	정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
continueOnError	false	선택	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조: 오류 규칙이 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 정책 오류 처리
enabled	true	선택	정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async	false	지원 중단됨	이 속성은 지원이 중단되었습니다.

하위 요소 참조

이 섹션에서는 <PublishMessage>의 하위 요소를 설명합니다.

<DisplayName>

name 속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값	해당 사항 없음
필수 여부	선택사항. <DisplayName>을 생략하면 정책의 name 속성 값이 사용됩니다.
유형	문자열
상위 요소	<PolicyElement>
하위 요소	없음

<DisplayName> 요소는 다음 구문을 사용합니다.

구문

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

예시

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

<Source>

게시할 메시지를 지정합니다.

메시지는 리터럴 텍스트, 흐름 변수 또는 메시지 템플릿 형식의 조합일 수 있습니다.

기본값	해당 사항 없음
필수 여부	필수
유형	문자열
상위 요소	<PublishMessage>
하위 요소	없음

<Source> 요소는 다음 구문을 사용합니다.

구문

 <Source>SOURCE</Source>

예시-1

다음 예시에서는 소스 메시지를 flow-var-1 흐름 변수의 값으로 설정합니다.

<Source>{flow-var-1}</Source>

예시-2

다음 예시에서는 소스 메시지를 source-message-text-01로 설정합니다.

<Source>source-message-text-01</Source>

<CloudPubSub>

<Topic>의 상위 요소입니다.

하나의 Pub/Sub 주제에만 게시할 수 있습니다. 따라서 <CloudPubSub> 요소에는 하나의 <Topic> 요소만 있을 수 있습니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	<PublishMessage>
하위 요소	<Topic>

<CloudPubSub> 요소는 다음 구문을 사용합니다.

구문

<CloudPubSub>
  <Topic>TOPIC_NAME</Topic>
</CloudPubSub>

예시

다음 예시는 <CloudPubSub> 요소의 선언을 보여줍니다.

<CloudPubSub>
  <Topic>projects/{request.header.project}/topics/{request.header.topic}</Topic>
</CloudPubSub>

<Topic>

<Source> 메시지를 게시할 Pub/Sub 주제를 지정합니다.

projects/project-id/topics/topic-name 형식으로 주제 이름을 지정해야 합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	<CloudPubSub>
하위 요소	없음

<Topic> 요소는 다음 구문을 사용합니다.

구문

<Topic>TOPIC_NAME</Topic>

예시

다음 예시에서는 게시할 Pub/Sub 주제를 지정합니다.

<Topic>projects/project-id-marketing/topics/topic-name-test1</Topic>

이 예시에서 project-id-marketing은 Google Cloud 프로젝트 ID이고 topic-name-test1은 <Source> 메시지를 게시해야 하는 주제입니다.

<IgnoreUnresolvedVariables>

Apigee가 해결되지 않은 변수를 발견하면 처리를 중지할지 여부를 지정합니다.

기본값	거짓
필수 여부	선택사항
유형	부울
상위 요소	<PublishMessage>
하위 요소	없음

해결되지 않은 변수를 무시하고 계속 처리하려면 값을 true로 설정하고, 그 외의 경우 false로 설정합니다. 기본값은 false입니다.

<IgnoreUnresolvedVariables>를 true로 설정하는 것은 <PublishMessage>의 continueOnError를 true로 설정하는 것과 다릅니다. continueOnError를 true로 설정하면 Apigee가 모든 오류를 무시하지만 변수의 오류를 무시하지 않습니다.

<IgnoreUnresolvedVariables> 요소는 다음 구문을 사용합니다.

구문

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

예시

다음 예시에서는 <IgnoreUnresolvedVariables>를 true로 설정합니다.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

흐름 변수

흐름 변수는 특정 데이터를 보관하는 객체이며 API 프록시 흐름의 컨텍스트에서 사용할 수 있습니다. 이러한 변수는 페이로드 정보, URL 경로, IP 주소, 정책 실행의 데이터와 같은 정보를 저장합니다. 흐름 변수에 대한 자세한 내용은 흐름 변수 사용을 참조하세요.

PublishMessage 정책이 Pub/Sub 주제에 성공적으로 게시되면 Apigee는 publishmessage.message.id 흐름 변수를 Pub/Sub 서버에서 반환된 messageId로 설정합니다. 흐름 변수는 문자열 유형이며 해당 변수는 프록시 요청 흐름 이후에서 사용할 수 있습니다. 요구사항에 따라 다른 다운스트림 정책에서 흐름 변수를 사용할 수 있습니다. 하지만 게시가 실패하면 Apigee는 publishmessage.message.id 변수를 설정하지 않으며 이 변수에 액세스하면 오류가 발생합니다.

다양한 유형의 흐름 변수에 대한 자세한 내용은 흐름 변수 참조를 확인하세요.

오류 코드

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	원인
steps.publishmessage.PermissionDeniedError	500	이 오류는 런타임 서비스 계정이 프록시 서비스 계정을 가장할 수 없거나 프록시 서비스 계정에 주제에 게시할 권한이 없는 경우에 발생합니다.
steps.publishmessage.ExecutionError	500	이 오류는 Pub/Sub에 메시지를 게시하는 중 예상치 않은 오류가 있을 때 발생합니다. 오류 메시지에서 오류 세부정보를 볼 수 있습니다.

오류 변수

정책에 실행 오류가 발생할 때마다 Apigee는 오류 메시지를 생성합니다. 오류 응답에서 이러한 오류 메시지를 볼 수 있습니다. 시스템에서 생성된 오류 메시지가 제품의 컨텍스트와 관련이 없을 경우가 많습니다. 메시지를 보다 의미 있게 만들기 위해 오류 유형에 따라 오류 메시지를 맞춤설정할 수 있습니다.

오류 메시지를 맞춤설정하려면 오류 규칙 또는 RaiseFault 정책을 사용하면 됩니다. 오류 규칙과 RaiseFault 정책의 차이점에 대한 자세한 내용은 FaultRules와 RaiseFault 정책 비교를 참조하세요. 오류 규칙과 RaiseFault 정책 모두에서 Condition 요소를 사용하여 조건을 확인해야 합니다. Apigee는 각 정책에 고유한 오류 변수를 제공하며 정책이 런타임 오류를 트리거할 때 오류 변수 값이 설정됩니다. 이러한 변수를 사용하여 특정 오류 조건을 확인하고 적절한 조치를 취할 수 있습니다. 오류 조건 확인에 대한 자세한 내용은 빌드 조건을 참조하세요.

변수	각 항목의 의미는 다음과 같습니다.	예
fault.name	fault.name은 런타임 오류 표에 나열된 오류 중 하나와 일치할 수 있습니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name Matches "UnresolvedVariable"
publishmessage.POLICY_NAME.failed	POLICY_NAME은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	publishmessage.publish-message-1.failed = true

정책 오류에 대한 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.