support importing by resource identity

[ansgarm]

This PR adds a new ImportStateWithIdentity method to Provider which is used in the ImportResourceState RPC handler to optionally pass a resource identity instead of a string id. Both still exist side-by-side and will for backwards compatibility.

Resources can now retrieve and set values in an identity like this to support import by identity:

Importer: &schema.ResourceImporter{
	StateContext: func(ctx context.Context, rd *schema.ResourceData, i interface{}) ([]*schema.ResourceData, error) {
		if rd.Id() != "" {
			return []*schema.ResourceData{rd}, nil // just return the resource data, since the string id is used
		}

		identity, err := rd.Identity()
		if err != nil {
			return nil, err
		}

		emailRaw, ok := identity.GetOk("email")
		if !ok {
			return nil, fmt.Errorf("error getting email from identity: %w", err)
		}

		email, ok := emailRaw.(string)
		if !ok {
			return nil, fmt.Errorf("error converting email to string")
		}

		if email == "" {
			return nil, fmt.Errorf("email cannot be empty")
		}

		err = rd.Set("email", email)
		rd.SetId(email) // TODO: document that this is still required with resource identity
		if err != nil {
			return nil, fmt.Errorf("error setting email: %w", err)
		}

		return []*schema.ResourceData{rd}, nil
	},
},

[austinvalle]

Great work Ansgar! I left a note about a potential helper, but that can be in a follow-up PR before stable release 👍🏻

[austinvalle]

I'm going to merge this now and cut a beta release 👍🏻