PublishMessage 정책

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

개요

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

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

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

인증 및 프록시 배포

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

`<PublishMessage>`

PublishMessage 정책을 지정합니다.

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

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

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

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

구문

<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>

예 - Source

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

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>this is a message template {flow-variable1}</Source>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

예 - UseMessageAsSource

이 <PublishMessage> 정책은 UseMessageAsSource 요소를 지정합니다.

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-2">
    <UseMessageAsSource>request</UseMessageAsSource>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

예 - Attributes

이 <PublishMessage> 정책은 Attributes 요소를 지정합니다.

<PublishMessage name="Publish-Message-3">
  <Source>this is a message template {flow-variable1}</Source>
  <Attributes>
    <Attribute name='attr-name-0'>fixed-value</Attribute>
    <Attribute name='another-attribute-name'>{request.queryparam.attr1}</Attribute>
    <Attribute name='a-third-attribute-name'>{request.queryparam.attr2:default-value}</Attribute>
  </Attributes>
  <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`로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 `true`로 설정합니다. 참조: 오류 규칙이 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 정책 오류 처리
`enabled`	참	선택사항	정책을 시행하려면 `true`로 설정합니다. 정책을 중지하려면 `false`로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
`async`	거짓	지원 중단됨	이 속성은 지원이 중단되었습니다.

하위 요소 참조

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

`<Attributes>`

Pub/Sub 메시지에 연결할 속성을 지정합니다.

각 속성은 키-값 쌍입니다. 속성에 연결된 이름은 고유해야 합니다. 각 값은 런타임에 메시지 템플릿을 통해 동적으로 결정됩니다.

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

<Attributes> 요소는 다음 문법을 사용합니다.

구문

  <Attributes>
    <Attribute name='NAME-1'>fixed-value</Attribute>
    <Attribute name='NAME-2'>{flow-variable}</Attribute>
    ...
    <Attribute name='NAME-N'>message template here {flow-variable:default-value}</Attribute>
  </Attributes>

예 1

다음 예시에서는 메시지가 게시될 때 고정된 값을 사용하여 단일 속성을 설정합니다.

<PublishMessage name="PM-with-one-attribute">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{request.queryparam.message}</Source>
  <Attributes>
    <Attribute name='my-attribute-1'>fixed-value</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{request.queryparam.project}/topics/{request.queryparam.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

예 2

다음 예시에서는 메시지가 게시될 때 메시지에 여러 속성을 설정합니다. 일부 속성의 값은 런타임에 동적으로 결정됩니다.

<PublishMessage name="PM-with-multiple-attributes">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{my-assembled-message}</Source>
  <Attributes>
    <Attribute name='attr-0'>fixed-value</Attribute>
    <Attribute name='attr-1'>{flow-variable1}</Attribute>
    <Attribute name='attr-2'>fixed portion {flow-variable2:default-value}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</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>

Example-1

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

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

Example-2

다음 예시에서는 메시지 템플릿을 사용하여 동적 콘텐츠가 포함된 JSON 메시지를 게시합니다.

<PublishMessage name="PM-with-source-template">
  <Source>{
    "name": "value-1",
    "count": "{flow-variable1}",
    "action": "{flow-variable2}"
  }</Source>
  <Attributes>
    <Attribute name='content-type'>application/json</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

`<CloudPubSub>`

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

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

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

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

구문

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

예

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

<CloudPubSub>
  <Topic>projects/{my-project}/topics/{my-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은 메시지를 게시해야 하는 주제입니다.

`<UseMessageAsSource>`

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

<Source> 요소의 대안으로 사용하세요. 값은 메시지를 참조하는 흐름 변수의 이름(예: request, response 또는 message)이어야 합니다. 이 요소를 지정하면 정책이 메시지의 콘텐츠를 게시할 메시지로 사용합니다. 메시지 콘텐츠가 문자열로 나타낼 수 없는 옥텟 스트림인 경우(예: 바이너리 파일의 콘텐츠) <Source> 대신 이 요소를 사용해야 합니다.

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

<UseMessageAsSource> 요소는 다음 문법을 사용합니다.

구문

<PublishMessage name="PM-with-use-message-as-source">
  <UseMessageAsSource>MESSAGE_NAME</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{flowvar1}/topics/{flowvar-topic}</Topic>
  </CloudPubSub>
</PublishMessage>

Example-1

다음 예시에서는 요청 메시지의 콘텐츠를 Pub/Sub 메시지의 페이로드로 사용하도록 정책에 지시합니다.

<PublishMessage name="PM-with-use-message-as-source">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <UseMessageAsSource>request</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

`<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 변수를 설정하지 않으며 이 변수에 액세스하면 오류가 발생합니다.

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

오류 코드

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.publishmessage.PermissionDeniedError`	`500`	This error occurs when the runtime service account cannot impersonate the proxy service account or the proxy service account does not have the permission to publish to the topic.
`steps.publishmessage.ExecutionError`	`500`	This error occurs if there was an unexpected error while publishing the message to Pub/Sub. You can view the details of the error in the error message.
`steps.publishmessage.MessageVariableNotMessageType`	`500`	This error occurs if the variable name you specified in `UseMessageAsSource` cannot be resolved, or is not a message type.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

Variables	Where	Example
`fault.name`	The `fault.name` can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`publishmessage.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`publishmessage.publish-message-1.failed = true`

For more information about policy errors, see What you need to know about policy errors

PublishMessage 정책 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

개요

인증 및 프록시 배포

<PublishMessage>

구문

예 - Source

예 - UseMessageAsSource

예 - Attributes

하위 요소 참조

<Attributes>

구문

예 1

예 2

<DisplayName>

구문

예

<Source>

구문

Example-1

Example-2

<CloudPubSub>

구문

예

<Topic>

구문

예

<UseMessageAsSource>

구문

Example-1

<IgnoreUnresolvedVariables>

구문

예

흐름 변수

오류 코드

Runtime errors

Fault variables

PublishMessage 정책

`<PublishMessage>`

`<Attributes>`

`<DisplayName>`

`<Source>`

`<CloudPubSub>`

`<Topic>`

`<UseMessageAsSource>`

`<IgnoreUnresolvedVariables>`