# Conversion mappings
<gh-file:pulumi#proto/pulumi/codegen/mapper.proto>

## Services

(codegen.Mapper)=
### 🔌 Mapper
Mapper provides methods for retrieving mappings that describe how to map names in some source "provider" (e.g. a
Terraform provider, if we are converting from Terraform) to names in appropriate Pulumi packages. So when converting
a Terraform program containing code like `resource "aws_s3_bucket" "b" {}`, for instance, we need to know (among
other things) that the `aws_s3_bucket` Terraform resource type corresponds to the Pulumi type `aws:s3/bucket:Bucket`,
and thus lives in the `aws` package. This is the kind of information that a Mapper provides.


(codegen.Mapper.GetMapping)=
#### 📞 GetMapping

⤵️ [GetMappingRequest](#codegen.GetMappingRequest) ⤴️ [GetMappingResponse](#codegen.GetMappingResponse)

`GetMapping` returns any available mapping data for the given source provider name (so again, this is e.g. the
name of a Terraform provider if converting from Terraform). Callers may pass "hints" that describe a Pulumi
package that is expected to provide the mapping and satisfy the request, which implementations may use to
optimise their efforts to return the best possible mapping. If no matching mapping exists, implementations should
return an empty byte array result.

## Messages
(codegen.GetMappingRequest)=
### 📨 GetMappingRequest
`GetMappingRequest` is the type of requests sent as part of a [](codegen.Mapper.GetMapping) call.


`provider` [string](#string)
:   The name of the source provider (e.g. the Terraform provider name if a Terraform program is being converted) for
  which a mapping into Pulumi should be returned.


`pulumi_provider` [string](#string)
:   The name of the Pulumi plugin that is expected to provide the mapping. If left empty, will be defaulted to the
  source provider name.


`parameterization_hint` [MapperParameterizationHint](#codegen.MapperParameterizationHint)
:   An optional parameterization that should be used on the named plugin before asking it for mappings.


`ecosystem` [string](#string)
:   The ecosystem whose mappings are being requested (e.g. "terraform"). This identifies the source ecosystem
  the caller consumes, which is not necessarily the caller's own name -- the hcl converter, for instance,
  executes Terraform programs and so requests "terraform" mappings. If left empty, the mapper falls back to
  the conversion key it was configured with: most mapper instances (those served to `plugin run` and to
  providers and language runtimes) default to "terraform", while `pulumi convert` and `pulumi import` default
  it to the source converter's plugin name. Setting this field lets a caller request a specific ecosystem
  regardless of that configured default, which is particularly useful for `plugin run` and providers
  accessing the mapper.

(codegen.GetMappingResponse)=
### 📨 GetMappingResponse
`GetMappingResponse` is the type of responses sent by [](codegen.Mapper.GetMapping) calls.


`data` [bytes](#bytes)
:   Conversion-plugin-specific mapping data. For a Terraform conversion, for instance, this is expected to be a piece
  of data that maps Terraform names (e.g. resource types) to Pulumi names (e.g. Pulumi resource types). In many
  cases this byte array will be a string of encoded JSON, but no specific format is required.

(codegen.MapperParameterizationHint)=
### 📨 MapperParameterizationHint
`MapperPackageParameterizationHint` is the type of hints that may be passed to [](codegen.Mapper.GetMapping) when it
is expected that a parameterized provider plugin is the most likely source of a mapping. E.g. in the case of a
dynamically bridged Terraform provider, callers may wish to express that a mapping is most likely offered by the
"terraform-provider" plugin, but only when it is parameterized with the appropriate Terraform provider information.


`name` [string](#string)
:   The package name expected once parameterization has been applied.


`version` [string](#string)
:   The package version expected once parameterization has been applied.


`value` [bytes](#bytes)
:   The parameter value to send to the provider plugin as part of parameterization.